Add tests for code examples in docs

[br3ndonland]

Description

The fastenv docs contain code examples to help people get started with the package.

Code examples can be helpful, but they can also get out-of-date and stop working. For this reason, it can be helpful to test the code examples.

The code examples are usually moved to separate files to make testing easier. pymdownx.snippets is already enabled, which allows us to embed external files in the docs.

fastenv/mkdocs.yml

Line 10 in 903a7de

- pymdownx.snippets

Suggestions

Pages in the docs could be updated like this:

• Make a new Python package directory for the docs.

  • Maybe name it fastenv_docs. FastAPI uses docs_src, but I would prefer fastenv_docs because it is more specific.
  • The package could go in the docs/ directory, or at the top-level of the repo. It might make sense to put the directory into docs/.

• Move code examples from Markdown code blocks into Python files in the fastenv_docs package.

• Update the Markdown code blocks to import the code examples from fastenv_docs as described in Material for MkDocs docs: Setup - Extensions - Python Markdown extensions - Snippets.

• Add tests for the code examples.

  • Tests could go into a new directory tests/fastenv_docs.

  • If needed, the same secrets from the other tests can be used in GitHub Actions.

    fastenv/.github/workflows/ci.yml

    Lines 92 to 101 in 903a7de

    	- name: Run tests
    	run: hatch run coverage run -m pytest --durations=0 --durations-min=0.1
    	timeout-minutes: 5
    	env:
    	AWS_IAM_ACCESS_KEY_FASTENV: ${{ secrets.AWS_IAM_ACCESS_KEY_FASTENV }}
    	AWS_IAM_ACCESS_KEY_SESSION: ${{ env.AWS_ACCESS_KEY_ID }}
    	AWS_IAM_SECRET_KEY_FASTENV: ${{ secrets.AWS_IAM_SECRET_KEY_FASTENV }}
    	AWS_IAM_SECRET_KEY_SESSION: ${{ env.AWS_SECRET_ACCESS_KEY }}
    	AWS_IAM_SESSION_TOKEN: ${{ env.AWS_SESSION_TOKEN }}
    	AWS_S3_BUCKET_HOST: ${{ secrets.AWS_S3_BUCKET_HOST }}

• Update test configurations in pyproject.toml to test the new files.

  fastenv/pyproject.toml

  Lines 98 to 100 in 903a7de

  	[tool.coverage.run]
  	command_line = "-m pytest"
  	source = ["fastenv", "tests"]

  fastenv/pyproject.toml

  Lines 111 to 114 in 903a7de

  	[tool.pytest.ini_options]
  	addopts = "-q"
  	minversion = "6.0"
  	testpaths = ["tests"]

• Update configurations for code quality tooling to check the new files.

  fastenv/pyproject.toml

  Lines 102 to 109 in 903a7de

  	[tool.isort]
  	profile = "black"
  	src_paths = ["fastenv", "tests"]
  	[tool.mypy]
  	files = ["**/*.py"]
  	show_error_codes = true
  	strict = true

To make it manageable, a PR could address one page of the docs at a time.

Future work could also add doctests (tests for REPL examples that start with >>>).

Related

• Python Markdown Extensions docs: Snippets
• Material for MkDocs docs: Setup - Extensions - Python Markdown extensions - Snippets
• FastAPI documentation code and tests for documentation code
• pydantic documentation code
• xdoctest (can run doctests, but maybe not on Markdown files yet)