DOC: Deploy docs to gh-pages from CircleCI - with versioning #65
Conversation
|
@rwblair What's the status of this? Should we try to get this merged today for a 0.3.0 release, or push off for now? |
|
@rwblair, they finally migrated sphinx-versioning to sphinx-contrib |
|
I think moving on to upgrading fMRIPrep's dependencies is probably more important than squeezing this in now. Sorry for the short turnaround question at lunch time. |
|
Ok I think this is ready. Documentation is being saved as an artifact so we can review it there. Once this gets merged and a new version tagged, we will need to blacklist this branch from sphinx-versioning so it doesn't show up in the side menu. |
|
Outstanding work! Will review ASAP
…On Tue, Aug 27, 2019, 12:45 Ross Blair ***@***.***> wrote:
Ok I think this is ready. Documentation is being saved as an artifact so
we can review it there. Once this gets merged and a new version tagged, we
will need to blacklist this branch from sphinx-versioning so it doesn't
show up in the side menu.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#65>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAESDRWN74Z2X5J2QR6E4Z3QGV76RANCNFSM4HBG2FWA>
.
|
|
"doc_test" in the left hand column is a tag I made on the ci_doc_deploy branch to test new tags. This is where the versions that have documentation will show up in the future. |
docs/api/smriprep.rst
Outdated
| Subpackages | ||
| ----------- | ||
|
|
||
| .. toctree:: |
There was a problem hiding this comment.
maybe this toctree should be moved to the docstring of smriprep/__init__.py replacing the description that is written currently, and removed from here. Then this block would only have (no sections):
.. automodule:: smriprep
:members:
:undoc-members:
:show-inheritance:There was a problem hiding this comment.
So this file is automatically generated by sphinx-apidoc, changes to it are overwritten.
Looks like in sphinx 2.2 you can overwrite the templates used in its generation with -t:
https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html
I'll try and get the base templates used and try modifying those.
There was a problem hiding this comment.
Is this really automatically generated by apidocs? That surprises me.
There was a problem hiding this comment.
The toctree itself is being pulled from smriprep/init.py. I got the template dir setting to work with apidoc and removed a few things from the packages.rst_t template to clean it up.
Maybe we push fine tweaking it into an aesthetic fixes PR.
Co-Authored-By: Oscar Esteban <code@oscaresteban.es>
Co-Authored-By: Oscar Esteban <code@oscaresteban.es>
Co-Authored-By: Oscar Esteban <code@oscaresteban.es>
Co-Authored-By: Oscar Esteban <code@oscaresteban.es>
Move docs requirements to docs directory pin sphinxcontrib-versioning to a tag remove subsection header in api/smriprep.rst Have versions in docs/conf.py match fmriprep Try moving subpacge toctree to smriprep/__init__.py
|
Tests look fixed. Any objections to merging @oesteban? Once this is merged I'll open up another PR that removes the doc_test_* tags and removes the ci_doc_deploy branch from being built via sphinxcontrib-versioning. |
|
I'll have a last look later today 👍 . Thanks very much for figuring this out. |
…work properly. changing circle config to reflect that. Update theme to rtd theme
| @@ -0,0 +1,4 @@ | |||
| Sphinx>=2.1.2 | |||
There was a problem hiding this comment.
Can you add/update these in setup.cfg under the doc extra?
There was a problem hiding this comment.
A useful tool we could include here, to keep things synced: https://github.com/nipy/nibabel/blob/master/tools/update_requirements.py
We could update it to also write out to docs/requirements.txt.
|
Looks like you need |
|
READY???? |
Closes #46.