docs: add README documenting docs build sources and outputs#848
Conversation
priyam0k
requested review from
genedan,
henrydingliu,
jbogaardt and
kennethshsu
as code owners
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #848 +/- ##
=======================================
Coverage 86.94% 86.94%
=======================================
Files 86 86
Lines 4994 4994
Branches 644 644
=======================================
Hits 4342 4342
Misses 462 462
Partials 190 190
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
@priyam0k this is great. what did you use to generate it? |
|
|
||
| The rendered site is written to `docs/_build/html/`. Open `docs/_build/html/index.html` in a browser to review changes. | ||
|
|
||
| `jb build .` reads `_config.yml` and `_toc.yml`, then hands off to Sphinx using the extensions declared in `conf.py`. A full build currently emits warnings; cleaning those up is tracked under [#841](https://github.com/casact/chainladder-python/issues/841). |
There was a problem hiding this comment.
I don't think this needs to be here?
There was a problem hiding this comment.
Agreed, dropping it. The warning callout is duplicated lower down and the internals sentence doesn't earn its keep.
| | `_toc.yml` | Book structure and page ordering. | | ||
| | `_config.yml` | Jupyter Book configuration (title, theme, Sphinx extensions). | | ||
| | `conf.py` | Sphinx configuration (autosummary, intersphinx, numpydoc, etc.). | | ||
| | `getting_started/` | Install, quickstart, and tutorial notebooks. | |
There was a problem hiding this comment.
Instead of "tutorial notebooks" I would change the wording to onboarding or Quickstart notebooks.
There was a problem hiding this comment.
True, switching to "onboarding and Quickstart notebooks."
| | You want to change... | Edit... | | ||
| | --- | --- | | ||
| | The home page | `intro.md` | | ||
| | Page order or sidebar nav | `_toc.yml` | | ||
| | Site title, theme, Sphinx extensions | `_config.yml` and `conf.py` | | ||
| | Which classes/functions appear in the API reference | `library/api.md` (autosummary lists) | | ||
| | The content of a class or function's API page | The docstring of that class/function in `chainladder/**/*.py` | | ||
| | Release notes | `library/releases.md` | | ||
| | A tutorial or user guide topic | The relevant notebook under `getting_started/` or `user_guide/` | | ||
| | A gallery example | The relevant notebook under `gallery/` | | ||
|
|
||
| ## Known issues | ||
|
|
||
| A clean `jb build .` currently emits a number of Sphinx warnings; cleanup is tracked in [#841](https://github.com/casact/chainladder-python/issues/841) and its sub-issues. Please do not silence warnings ad-hoc as part of unrelated PRs. |
There was a problem hiding this comment.
I don't think anything here needs to be shown?
There was a problem hiding this comment.
Agreed, the table mostly restates the Source files table above, and the warnings note is repeated. Removing both.
Thanks! Drafted with Copilot / Claude after reading through the docs setup myself, then checked each path and command against the repo before pushing. Happy to tweak wording. |
- Drop the jb build internals + duplicate warnings note (kennethshsu) - Rename 'tutorial notebooks' to 'onboarding and Quickstart notebooks' (kennethshsu) - Drop the 'What to edit for which part of the site' table and 'Known issues' section as redundant with the Source files table and casact#841 (kennethshsu)
|
@priyam0k thanks for putting this together this looks so hype :D |
3 participants
Closes #845. Refs parent #841.
Adds a
docs/README.mddocumenting how the docs site is built and which files are sources vs. generated, so future contributors do not have to reverse-engineer it.The README covers:
pip install -e .[docs]thencd docs && jb build .) and where the rendered output lands.intro.md,_toc.yml,_config.yml,conf.py, thegetting_started//user_guide//gallery/notebooks,library/api.md,library/releases.md)._build/from Sphinx,library/generated/*.rstfromsphinx.ext.autosummary).No code or config changes; docs-only addition. The companion cleanup for the redundant generated stubs is in #846.
Note
Low Risk
Documentation-only addition with no runtime, config, or API behavior changes.
Overview
Adds
docs/README.mdas contributor-facing documentation for the Jupyter Book / Sphinx docs tree.It documents how to build locally (
pip install -e .[docs], thenjb build .indocs/), where output lands (docs/_build/html/), and optionalmaketargets. Tables map editable sources (intro.md,_toc.yml,_config.yml,conf.py, notebook folders,library/api.md, etc.) versus generated artifacts (_build/,library/generated/*.rstfrom autosummary). It also explains that new API symbols are added vialibrary/api.mdand package docstrings, not hand-written.rststubs.Reviewed by Cursor Bugbot for commit 9669d2d. Bugbot is set up for automated code reviews on this repo. Configure here.