Skip to content

Migrate documentation to use Markdown and MkDocs #1397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Dec 24, 2024
Merged

Conversation

tleonhardt
Copy link
Member

@tleonhardt tleonhardt commented Dec 23, 2024

Migrate documentation to use MkDocs with the Material Theme for the build. Replaced all use of reStructuredText with Markdown and all use of Sphinx with MkDocs.

TODO:

  • Create MkDocs Material theme basic setup and configuration
  • Translate reStructuredText docs to Markdown using pandoc
  • Verify MkDocs build and serve are working
  • Delete Sphinx stuff and make sure GitHub Actions doc build is working
  • Finish correcting basic translation errors
  • Get automated API documentation using mkdocstrings working nicely
  • Figure out how to do autodoc references using mkdocstring
  • Final cleanup check of markdown
  • Make recommended tweaks for hosting docs on ReadTheDocs
  • Add example of using mermaid to embed diagrams in scripting.md
  • Verify ReadTheDocs build is working properly

Closes #1396

…ocumentation

TODO:
1. Finish correcting translation - I stopped at features/disable_commands
2. Get all the autodoc API stuff working properly
3. Get ReadTheDocs working properly
@tleonhardt tleonhardt requested a review from anselor as a code owner December 23, 2024 20:30
@tleonhardt tleonhardt changed the title [WIP] Migrate documentation to use Markdown and MkDocs Migrate documentation to use Markdown and MkDocs Dec 23, 2024
@tleonhardt
Copy link
Member Author

@kotfu @kmvanbrunt This PR is now ready for your review. Everything appears to work and I'm happy with the way it looks. I think there is a tremendous amount of room for further improvement down the road given the overall capabilities of the MkDocs Material Theme, but this seems like a great start.

@tleonhardt
Copy link
Member Author

tleonhardt commented Dec 24, 2024

The docs this PR generates can be viewed as built by ReadTheDocs here.

They are fully working other than the search - ReadTheDocs serves PR builds from a different domain than normal which is why I think that is broken. It should work in an actual build off the master branch.

There is a little button in the top center that looks like a sun or moon which you can use toggle between dark and light mode and your browser will remember the setting for the same page if viewed again.

@tleonhardt tleonhardt merged commit 9d3f227 into master Dec 24, 2024
47 checks passed
@tleonhardt tleonhardt deleted the mkdocs_material branch December 24, 2024 16:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Convert documentation from Sphinx to MkDocs
2 participants