readthedocs / readthedocs/sphinx-autoapi

Markdown support

Open
#287 10 comments 11 reactions 0 assignees View on GitHub

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:

  1. Cast the existing templates into Markdown. Includes using a (potential) sphinx.util.docstrings.prepare_docstring analog from myst. This is to allow two sets of default templates to exist.
  2. 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.