Repository navigation
Conversation
Group the template's docs sidebar into Getting started, Guides, Reference and Project as agreed in scverse/scverse-doc#62. New installation and quickstart pages fill Getting started, a citation page includes the README's Citation section, and References is renamed to Bibliography so it doesn't clash with the Reference caption. GitHub and Discourse links under Project are left out as decided at the end of scverse-doc#62, since the repository button and the README's Contact section already cover them. The new pages are excluded from template updates like index.md, otherwise existing projects would get them as orphans and fail their -W docs build.
|
A PR has been generated to the instance repo: scverse/cookiecutter-scverse-instance#332
You can check out the PR to preview your changes in an instance of the cookiecutter template. |
The installation page now uses the same sphinx-design tabs as the contributing guide instead of a one-item numbered list. A commented-out PyPI section with the same tabs is ready to uncomment after the first release.
Splitting api.md into api/preprocessing.md, api/tools.md and api/plotting.md like pertpy nests these groups under API in the sidebar. Autosummary still writes to docs/generated, so generated URLs and the .gitignore entry stay the same. docs/api is skipped by cruft and excluded from template updates like api.md, otherwise existing projects would get duplicate module declarations.
|
@grst I saw your comment about the installation instructions but I think having this minor duplication is okay. It looks cooler like https://scanpy.readthedocs.io/en/stable/installation.html (after some more optimization) and I don't mind having to update the Python version twice. But please feel free to make changes to this PR! |
There was a problem hiding this comment.
citation is also included in index.md.
Either there or here!
| @@ -1,18 +1,42 @@ | |||
| ```{include} ../README.md | |||
|
|
|||
There was a problem hiding this comment.
I didn’t check if the syntax is correct
| :end-before: "## Citation" |
grst
left a comment
grst
left a comment
There was a problem hiding this comment.
I think we also said that README should now include a brief statement of the scope of the package (what does it do and how does it relate to scverse). Can we also include a template statement for that in this PR?
| @@ -0,0 +1,60 @@ | |||
| # Installation | |||
There was a problem hiding this comment.
As pointed out in scverse/scirpy#761, I'm not a big fan of duplicating the installation instructions from the README.
We could either
- include contents from the README here, using the
:start-after:and:end-beforedirectives I just learned about - treat the new
installation.mdas the single source of truth for installation and just refer to this from the README, or just include the canonical installation route (pip install xxx) in the README and refer to here for all special cases (development version, conda etc.).
There was a problem hiding this comment.
I vote for a canonical installation route in th README and all special cases on the installation page. The README will not have nice tabs for pypi, conda, ... and other details.
|
The new scverse-doc change inspired by this has some beautiful results: these are now no longer clickable and no longer lead to useless toctree-only pages, which only exist to make these toctree headers exist. 
Needs a heads-up though, as it can lead to issues (e.g. all APIs are grouped under “Array API support” in scanpy’s docs without changes) |
Closes #579.
Groups the template's docs sidebar into Getting started, Guides, Reference and Project as agreed in scverse/scverse-doc#62, with new installation, quickstart and citation pages, one API page per module, and "References" renamed to "Bibliography".
The new pages are excluded from template updates like
docs/index.mdanddocs/api.md, so only newly created projects get the new structure.