Add Sphinx documentation site with auto-generated example pages - #486
Add Sphinx documentation site with auto-generated example pages#486dietcoke-17 wants to merge 2 commits into
Conversation
for more information, see https://pre-commit.ci
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6b6f92bf05
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| f"# {display_name(example_name)}\n\n" | ||
| f"```{{include}} {rel_readme}\n" | ||
| f":relative-images:\n" | ||
| f":relative-docs: {rel_dir}/\n" |
There was a problem hiding this comment.
When an included README links to sibling files (for example examples/el_farol/README.md links to el_farol.ipynb, model.py, and tests.py), those links do not start with the configured ../../examples/.../ prefix. MyST's relative-docs only rewrites links that match that prefix, so Sphinx resolves these as files under docs/examples/ that are not generated or copied, leaving broken links in the published pages. Please rewrite these README-local links to source/GitHub URLs or copy/link the target files into the docs output.
Useful? React with 👍 / 👎.
| extensions = [ | ||
| "myst_parser", | ||
| "sphinx_copybutton", | ||
| ] |
There was a problem hiding this comment.
Several included READMEs use raw HTML image tags with relative src values, such as rl/boltzmann_money/README.md and examples/virus_antibody/README.md. This config only relies on :relative-images:, while MyST requires the optional html_image support (or preprocessing) to parse HTML images; otherwise those src="ppo_agent.gif"/src="images/..." paths pass through unchanged and the RTD HTML looks for files beside the generated page where nothing is copied. Please enable/convert these HTML images or copy them into the output.
Useful? React with 👍 / 👎.
|
Thanks for the PR but Lets first reach on a consensus in issue. |
2 participants
Fixes : #484
Add Sphinx-based documentation for mesa-examples, auto-generated from each example's own
README.md, and wire it up for Read the Docs hosting.docs/conf.py: Sphinx config (MyST + sphinx-copybutton + pydata-sphinx-theme) that scansexamples/,gis/, andrl/at build time and generates a page per example plus a per-category index — no docs content is hand-maintained.docs/index.md: landing page linking the three category toctrees..readthedocs.yaml: RTD v2 build config.pyproject.toml: newdocsextra (sphinx,myst-parser,pydata-sphinx-theme,sphinx-copybutton)..gitignore: ignore the auto-generateddocs/examples*,docs/gis*,docs/rl*output.