Adding MkDocs docs to template by matt-graham · Pull Request #319 · UCL-ARC/python-tooling

matt-graham · 2024-03-20T19:18:22Z

Would resolve #16 as an alternative to #318

Adds MkDocs documentation to template, aiming for a comparable set of features to what is implemented in #318 - automatically built API documentation with Markdown syntax, support for references to external documentation inventories, dark / light mode toggle, GitHub repository link in docs, workflow for automatically testing building docs.

Example screenshot of rendered index page

and of API reference page

matt-graham · 2024-03-20T19:26:20Z

I got a not very helpful SyntaxError: All collection items must start at the same column (1:1) error from prettier when first trying to commit the mkdocs.yml file which was eventually resolved by some trial and error of adding additional quotation marks around some of the string values.

If we're going the MkDocs route, I would say we might want to review use of Prettier for YAML files as I can imagine the experience for users of getting a message like this when trying to commit changes to mkdocs.yml would be a bit painful.

Prettier output

[error] {{cookiecutter.project_slug}}/mkdocs.yml: SyntaxError: All collection items must start at the same column (1:1)
[error] >  1 | site_name: {{cookiecutter.project_name}}
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] >  2 | site_description: Documentation website for {{cookiecutter.project_name}}
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] >  3 | site_author: {{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] >  4 | copyright: © {% now 'utc', '%Y' %}, {{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] >  5 | repo_url: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] >  6 | repo_name: {{cookiecutter.github_username}}/{{cookiecutter.project_slug}}
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] >  7 |
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] >  8 | theme:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] >  9 |   name: "material"
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 10 |   palette:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 11 |     - media: "(prefers-color-scheme)"
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 12 |       toggle:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 13 |         icon: material/brightness-auto
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 14 |         name: Switch to light mode
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 15 |     - media: "(prefers-color-scheme: light)"
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 16 |       scheme: default
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 17 |       toggle:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 18 |         icon: material/brightness-7
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 19 |         name: Switch to dark mode
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 20 |     - media: "(prefers-color-scheme: dark)"
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 21 |       scheme: slate
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 22 |       toggle:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 23 |         icon: material/brightness-4
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 24 |         name: Switch to system preference
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 25 |   icon:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 26 |     repo: fontawesome/brands/github
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 27 |
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 28 | nav:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 29 |   - index.md
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 30 |   - api.md
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 31 |
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 32 | plugins:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 33 |   - search
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 34 |   - mkdocstrings:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 35 |       default_handler: python
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 36 |       handlers:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 37 |         python:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 38 |           docstring_style: google
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 39 |           import:
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 40 |           - https://docs.python.org/3/objects.inv
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 41 |           paths: [src]
[error]      | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[error] > 42 |
[error]      |

paddyroddy · 2024-03-20T21:49:46Z

If we're going the MkDocs route, I would say we might want to review use of Prettier for YAML files as I can imagine the experience for users of getting a message like this when trying to commit changes to mkdocs.yml would be a bit painful.

I do think a lot of the difficulties arise from cookiecutter templating in the files. We may need to exclude stuff at the top level .pre-commit-config.yaml - as is done in other hooks.

paddyroddy

In case we go with this approach, I have given a review.

Co-authored-by: Patrick J. Roddy <patrickjamesroddy@gmail.com>

…ugin

samcunliffe

Thanks a lot for dual-wielding the docs builds!

Fixes #187. Relates to #16, #318, and #319. See discussion in #16. Depends on #319.

Co-authored-by: Sam Cunliffe <samcunliffe@users.noreply.github.com>

paddyroddy

Looks good!

Following the discussion in #16, I've tried to summarise (and might have quoted you directly 😄). Picky comments very gratefully received. ## Fixes - #187 ## Relates to - #16 - #318 - #319 --------- Co-authored-by: Matt Graham <matthew.m.graham@gmail.com> Co-authored-by: David Stansby <dstansby@gmail.com>

Fixes #296 and fixes #305 Adds longer human-readable prompts for all cookiecutter template options using the `prompts` field in `cookiecutter.json` (we already had a prompt for `deploy_docs_to_github_pages` option from #319). --------- Co-authored-by: David Stansby <dstansby@gmail.com>

Adding MkDocs docs to template

a5f0d52

matt-graham marked this pull request as draft March 20, 2024 19:27

Add new line in docstring to satisfy Ruff

36a4fbd

matt-graham mentioned this pull request Mar 20, 2024

Add documentation #16

Closed

matt-graham added 9 commits March 21, 2024 08:36

Avoid repetition of docs dependencies

d33e871

Fix typo and make title case consistent

d605092

Format frameworks as a list

ec12b11

Add edit URI for GitHub links

788c9f7

Use MkDocs recommended stricter validation

ebebf85

Add GitHub social link

0de39ae

Include README and license content in docs

81fa625

Tweak copyright line

248f1f3

Correct reference to docs dependencies

0648c3a

matt-graham mentioned this pull request Mar 21, 2024

Always ignore template at top level pre-commit #320

Merged

matt-graham added the enhancement New feature or request label Mar 21, 2024

matt-graham added 2 commits March 21, 2024 09:13

Rename license file in docs to make relative link from README work

04884a5

Add edit buttons to docs

f16841b

paddyroddy requested changes Mar 22, 2024

View reviewed changes

paddyroddy and others added 10 commits March 22, 2024 11:25

Merge branch 'main' into mmg/mkdocs-docs

414fd18

Apply suggestions from code review

442992e

Co-authored-by: Patrick J. Roddy <patrickjamesroddy@gmail.com>

Reorder tox testenv sections

2e67533

Co-authored-by: Patrick J. Roddy <patrickjamesroddy@gmail.com>

Add quotation marks around URL for consistency

f48174e

Add vertical spacing between docs workflow job steps for consistency

483a19e

Co-authored-by: Patrick J. Roddy <patrickjamesroddy@gmail.com>

Adjust commented section indentation

2f6bace

Remove spaces on empty lines

c36eb4f

Add option to enable automatically docs to GitHub Pages to cookiecutter

dfa918a

Adjust newlines and whitespace control in template to satisfy prettier

5c874cf

Switch from pymdownx.snippets extension to mkdocs-include-markdown-pl…

c23d7e6

…ugin

Remove indentation in include-markdown directive to satisfy prettier

832b262

matt-graham marked this pull request as ready for review March 22, 2024 17:42

matt-graham mentioned this pull request Mar 22, 2024

Adding Sphinx docs to template #318

Closed

4 tasks

paddyroddy reviewed Mar 22, 2024

View reviewed changes

Comment thread cookiecutter.json

samcunliffe reviewed Mar 22, 2024

View reviewed changes

Comment thread {{cookiecutter.project_slug}}/.github/workflows/docs.yml

Comment thread {{cookiecutter.project_slug}}/README.md Outdated

Comment thread {{cookiecutter.project_slug}}/docs/api.md

samcunliffe added a commit that referenced this pull request Mar 24, 2024

Update doc builder recommendations.

bff94dd

Fixes #187. Relates to #16, #318, and #319. See discussion in #16. Depends on #319.

samcunliffe mentioned this pull request Mar 24, 2024

Update doc builder recommendations. #327

Merged

Update {{cookiecutter.project_slug}}/README.md

fbb1d62

Co-authored-by: Sam Cunliffe <samcunliffe@users.noreply.github.com>

samcunliffe approved these changes Mar 25, 2024

View reviewed changes

paddyroddy approved these changes Mar 25, 2024

View reviewed changes

matt-graham merged commit 925fce9 into main Mar 25, 2024

matt-graham deleted the mmg/mkdocs-docs branch March 25, 2024 11:33

matt-graham mentioned this pull request Mar 25, 2024

Document next steps for the user once they run the tool #205

Closed

samcunliffe mentioned this pull request Mar 25, 2024

Add our 🟢 tools. #1

Closed

22 tasks

matt-graham mentioned this pull request Jun 4, 2024

Adding longer prompts for all cookiecutter options #380

Merged

Navigation Menu

Uh oh!

Adding MkDocs docs to template - #319

Adding MkDocs docs to template#319
matt-graham merged 25 commits into
mainfrom
mmg/mkdocs-docs

matt-graham commented Mar 20, 2024

Uh oh!

matt-graham commented Mar 20, 2024 •

edited

Loading

Uh oh!

paddyroddy commented Mar 20, 2024

Uh oh!

paddyroddy left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samcunliffe left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

paddyroddy left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

matt-graham commented Mar 20, 2024

Uh oh!

matt-graham commented Mar 20, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paddyroddy commented Mar 20, 2024

Uh oh!

paddyroddy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samcunliffe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

paddyroddy left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

matt-graham commented Mar 20, 2024 •

edited

Loading