DOC: Build versioned docs and deploy them to gh-pages #45
Conversation
|
Best reviewed: commit by commit
Optimal code review plan (1 warning)
|
|
Hello @oesteban, Thank you for updating!
To test for issues locally, Comment last updated at 2019-12-12 07:36:58 UTC |
This PR adds three new build steps to our CircleCI workflow. The first one, called ``build_docs`` generates the documentation of the project using sphinx. In the case the commit message contains the tag ``[docs versions]`` (or a few variations thereof), then a readthedocs-style of versioned documentation is built. The other two build steps are run only for tag-commits and the master branch, to deploy the new versioned documentation to GitHub pages. I've set up the corresponding write-access keys in the repo and CircleCI, so this first step towards having documentation should fairly good to go.
|
Finally :). The pre-render of the docs is here: https://154-206670456-gh.circle-artifacts.com/0/root/project/docs/_build/no_version_html/html/index.html This will be very useful to visualize finalized workflows (see https://154-206670456-gh.circle-artifacts.com/0/root/project/docs/_build/no_version_html/html/api/dmriprep.workflows.base.html) Also, it will be possible to have a nice view of the docstrings and doctest examples we embed in our code (e.g., latest additions by @dPys on https://154-206670456-gh.circle-artifacts.com/0/root/project/docs/_build/no_version_html/html/api/dmriprep.utils.vectors.html) |
|
An additional feature is: by using Nipype's sphinx extension to generate the workflow graph we are exercising the workflow creation function (is a kind of implicit unit test :)) |
Codecov Report
@@ Coverage Diff @@
## master #45 +/- ##
=======================================
Coverage 54.66% 54.66%
=======================================
Files 11 11
Lines 772 772
Branches 116 116
=======================================
Hits 422 422
Misses 349 349
Partials 1 1
Continue to review full report at Codecov.
|
|
These look great! |
|
Yep, I'm eager to see the graph of new workflows in #25 |
| * within a `Manually Prepared Environment (Python 3.5+)`_, also known as | ||
| *bare-metal installation*; or | ||
| * using container technologies (RECOMMENDED), such as | ||
| `Docker <https://fmriprep.readthedocs.io/en/stable/docker.html>`__ or |
There was a problem hiding this comment.
remove references to running fmriprep via Docker and Singularity
There was a problem hiding this comment.
Eventually, we will generate these docs - but for now, I guess we need to pull from fMRIPrep for this.
| https://docs.docker.com/get-started/ | ||
|
|
||
| After checking your Docker Engine is capable of running Docker images, then go ahead | ||
| and `check out our documentation <https://fmriprep.readthedocs.io/en/stable/docker.html>`__ |
There was a problem hiding this comment.
Yup, same as above. I didn't want to copy the whole thing.
| .. warning:: | ||
|
|
||
| This method is not recommended! Please checkout container alternatives | ||
| such as `Docker <https://fmriprep.readthedocs.io/en/stable/docker.html>`__, or |
| sphinx-argparse | ||
| sphinx_rtd_theme | ||
| sphinxcontrib-apidoc ~= 0.3.0 | ||
| sphinxcontrib-napoleon |
There was a problem hiding this comment.
should the versions in requirements.txt also be pinned here?
There was a problem hiding this comment.
They should not for link-dependencies (i.e., pointing to a github repo and commit directly). If you did then Pypi will not accept the package :(. This is the case of napoleon and versioning.
Co-Authored-By: Michael Joseph <[email protected]>
Co-Authored-By: Michael Joseph <[email protected]>
Co-Authored-By: Michael Joseph <[email protected]>
|
I'll go ahead and merge since we want to test the actual deployment from master. |
This PR adds three new build steps to our CircleCI workflow.
The first one, called
build_docsgenerates the documentationof the project using sphinx.
In the case the commit message contains the tag
[docs versions](or a few variations thereof), then a readthedocs-style of versioned
documentation is built.
The other two build steps are run only for tag-commits and the master
branch, to deploy the new versioned documentation to GitHub pages.
I've set up the corresponding write-access keys in the repo and
CircleCI, so this first step towards having documentation should fairly
good to go.