readthedocs / readthedocs/sphinx-autoapi
Markdown support
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 494
- Forks
- 147
- Avg merge
- 9m
- Merged PRs (30d)
- 1
Description
I'm currently moving our tutorial notebooks/documentation from RST with jupyter-sphinx to Markdown with myst-nb. We'd eventually like to also move docstrings to be written in myst-markdown. To that end I'm now looking at what I actually need from sphinx-autoapi to make that possible. I came up with this:
- Cast the existing templates into Markdown. Includes using a (potential)
sphinx.util.docstrings.prepare_docstringanalog from myst. This is to allow two sets of default templates to exist. - Make the hardcoded
'*.rst'instances in template loading/rendering (mappers/base.py) use some config value instead. The actual file output suffix is already (not really explicitly) configurable.
I'd be happy to contribute this. If I was to do this just for our project, I'd still have to do step 1., but keep the .rst filenames. And step 2. seems pretty trivial.
What do you think?
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in mappers/base.py by tracing template loading and rendering, then inspect the existing configuration for the output suffix. Define how separate RST and Markdown template sets should be selected, convert the existing templates for Markdown, and replace hardcoded '*.rst' uses with configuration; done means Markdown tutorial and API documentation can be generated without breaking RST output.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100