Skip to content

Convert template docs to use markdown#18

Merged
coretl merged 8 commits into
mainfrom
docs-with-markdown
Feb 9, 2024
Merged

Convert template docs to use markdown#18
coretl merged 8 commits into
mainfrom
docs-with-markdown

Conversation

@callumforrester
Copy link
Copy Markdown
Contributor

@callumforrester callumforrester commented Jan 18, 2024 •
edited
Loading

This PR consists of two stages:

Conversion

  • Convert docs to markdown using myst
  • Use :glob: directive to partly generate toctrees

Simplification

  • Remove the developer guide from the docs shipped with the template and simplify them to essentially just be the user guide.
  • Add a small section on development to the templatised contributing guide with a link to the main developer docs

@callumforrester callumforrester marked this pull request as ready for review January 23, 2024 16:27
coretl
coretl reviewed Jan 24, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@coretl coretl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't find the reference to :global: can you point me to it please?

Comment thread template/{% if docs_type=="sphinx" %}docs{% endif %}/explanations/docs-structure.md
Comment thread template/{% if docs_type=="sphinx" %}docs{% endif %}/index.md Outdated
@callumforrester
Copy link
Copy Markdown
Contributor Author

callumforrester commented Jan 24, 2024

I can't find the reference to :global: can you point me to it please?

It should be :glob:, have I called it :global: anywhere?
https://sphinx-doc-zh.readthedocs.io/en/latest/markup/toctree.html

@coretl coretl mentioned this pull request Jan 29, 2024
Merged
callumforrester
callumforrester commented Jan 29, 2024
View reviewed changes
Comment thread template/{% if docs_type=="sphinx" %}docs{% endif %}/tutorials.md Outdated
@coretl coretl mentioned this pull request Jan 30, 2024
Closed
14 tasks
@coretl
Copy link
Copy Markdown
Contributor

coretl commented Jan 31, 2024

We should also update ADR 0002 title and content while doing this PR

@coretl coretl linked an issue Feb 1, 2024 that may be closed by this pull request
Convert docs to markdown #51
Closed
@callumforrester callumforrester force-pushed the docs-with-markdown branch 5 times, most recently from 196aa0d to f1d6d82 Compare February 5, 2024 15:01
@callumforrester callumforrester changed the title Convert docs to use markdown and move developer guide to docs Convert template docs to use markdown Feb 5, 2024
coretl
coretl reviewed Feb 6, 2024
View reviewed changes
Comment thread template/README.md.jinja Outdated
Comment thread template/README.md.jinja Outdated
Comment thread template/pyproject.toml.jinja Outdated
Comment thread template/{% if sphinx %}docs{% endif %}/explanations.md Outdated
Comment thread .../{% if sphinx %}docs{% endif %}/explanations/decisions/0001-record-architecture-decisions.md Outdated
Comment thread template/{% if sphinx %}docs{% endif %}/explanations/decisions/0002-switched-to-pip-skeleton.md
Comment thread template/{% if sphinx %}docs{% endif %}/how-to.md Outdated
Comment thread template/{% if sphinx %}docs{% endif %}/index.md
@coretl
Copy link
Copy Markdown
Contributor

coretl commented Feb 9, 2024

CI fails when running tox -p on the generated example with:
checking consistency... /tmp/pytest-of-runner/pytest-0/test_template0/project/docs/developer/how-to/coverage.md: WARNING: document isn't included in any toctree

I'll fix that in another PR then come back to this one...

@coretl
Copy link
Copy Markdown
Contributor

coretl commented Feb 9, 2024

Power cycling to re-run CI...

@coretl coretl closed this Feb 9, 2024
@coretl coretl reopened this Feb 9, 2024
@coretl coretl merged commit c78ba43 into main Feb 9, 2024
@coretl coretl deleted the docs-with-markdown branch February 9, 2024 14:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@coretl coretl coretl approved these changes

@M-Chan M-Chan Awaiting requested review from M-Chan

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Convert docs to markdown

2 participants

@callumforrester @coretl