🎨 Move some build info from CI to general repository (#252)

Author: shnizzedy

.circleci/config.yml

@@ -14,8 +14,9 @@ commands:
           name: ↑ Installing build dependencies
           command: |
             sudo apt-get update && sudo apt-get -y install git python3-dev graphviz graphviz-dev libgraphviz-dev pkg-config python3-sphinx
+            pip install --user -r requirements.txt
             pip install --user -r https://raw.githubusercontent.com/FCP-INDI/C-PAC/<< parameters.version >>/requirements.txt
-            pip install --user git+https://github.com/${CIRCLE_PROJECT_USERNAME}/C-PAC.git@<< parameters.version >> sphinx m2r numpydoc PyGithub "sphinxcontrib-bibtex<2.0" sphinxcontrib-fulltoc sphinxcontrib-programoutput semver torch
+            pip install --user git+https://github.com/${CIRCLE_PROJECT_USERNAME}/C-PAC.git@<< parameters.version >>
             git clone https://github.com/${CIRCLE_PROJECT_USERNAME}/C-PAC.git /home/circleci/build/C-PAC
             cd /home/circleci/build/C-PAC
             git checkout << parameters.version >>
@@ -24,13 +25,6 @@ commands:
             source ~/simple/bin/activate
             pip install cpac
             deactivate
-      - run:
-          name: 🖇️ Linking references
-          command: |
-            CPAC_DIRECTORY=$(python -c "import os, CPAC; print(os.path.abspath(os.path.dirname(CPAC.__file__)))")
-            ln ${CPAC_DIRECTORY}/resources/configs/1.7-1.8-nesting-mappings.yml docs/_sources/references/1.7-1.8-nesting-mappings.yml || true
-            ln ${CPAC_DIRECTORY}/resources/configs/1.7-1.8-deprecations.yml docs/_sources/references/1.7-1.8-deprecations.yml || true
-            curl -o docs/_sources/references/default_pipeline.yml -L https://raw.githubusercontent.com/${CIRCLE_PROJECT_USERNAME}/C-PAC/<< parameters.version >>/dev/docker_data/default_pipeline.yml || true
   
   run-cpac-commands:
     steps:
@@ -39,7 +33,7 @@ commands:
           name: 👊 Running cpac commands
           command: |
             source ~/simple/bin/activate
-            cpac run --help
+            cpac pull
             mkdir -p docs/_sources/user/cpac
             printf ".. code-block:: console\n\n   $ cpac --help\n\n" > docs/_sources/user/cpac/help.rst
             cpac --help | sed -e "s/.*/   &/" >> docs/_sources/user/cpac/help.rst

CONTRIBUTING.md

@@ -1,13 +1,33 @@
+<!-- TOC -->
+
+- [Branches](#branches)
+    - [Versions](#versions)
+        - [`nightly`](#nightly)
+        - [C-PAC release tags](#c-pac-release-tags)
+- [Guidelines](#guidelines)
+    - [Building](#building)
+        - [Let CircleCI build your drafts / works-in-progress](#let-circleci-build-your-drafts--works-in-progress)
+        - [Build locally (C-PAC ≥ v1.8.0)](#build-locally-c-pac-≥-v180)
+- [Flowcharts](#flowcharts)
+- [References and citations](#references-and-citations)
+- [Environment notes](#environment-notes)
+
+<!-- /TOC -->
+
+<a id="markdown-branches" name="branches"></a>
 ## Branches
 
 Please, always base changes on the `source` branch. `master` branch will be overwritten by the CI deployment.
 
+<a id="markdown-versions" name="versions"></a>
 ### Versions
 
+<a id="markdown-nightly" name="nightly"></a>
 #### `nightly`
 
 Pushes to `source` will rebuild docs at https://fcp-indi.github.io/docs/nightly
 
+<a id="markdown-c-pac-release-tags" name="c-pac-release-tags"></a>
 #### C-PAC release tags
 Tags in the format `v.*-source` will build docs for the given version.
 
@@ -21,6 +41,7 @@ Steps to build a release:
 5. (Force) push to the remote tag (`git push origin v`version`-source`).
 6. CircleCI should deploy the versioned documentation. If the version tag is the newest, it should also overwrite `latest` with these documents. 
 
+<a id="markdown-guidelines" name="guidelines"></a>
 ## Guidelines
 
 - Only write a document once, and liberally use the [reStructured Text `.. include::` directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#include) to include that document where appropriate.
@@ -37,16 +58,50 @@ Steps to build a release:
   '
   "
   ```
-- Let CircleCI build your drafts / works-in-progress
-    * Build environment will match actual docs build environment
-    * CircleCI takes ~2 minutes to build
-    1. Fork https://github.com/FCP-INDI/fcp-indi.github.com
-    1. In your fork's settings, set the GitHub Pages `source` to `master` branch
-        ![GitHub Pages settings example screenshot](./images/github-pages-settings-example.png)
-    1. Add your project on CircleCI
-    1. Merge your draft / work-in-progress into your fork's `source` branch. Make sure you push to your fork and not the main repository's `source` branch.
-    1. Your fork will publish at `https://[your_GitHub_username].github.io/fcp-indi.github.com/`.
 
+<a id="markdown-building" name="building"></a>
+### Building
+
+<a id="markdown-let-circleci-build-your-drafts--works-in-progress" name="let-circleci-build-your-drafts--works-in-progress"></a>
+#### Let CircleCI build your drafts / works-in-progress
+* Build environment will match actual docs build environment
+* CircleCI takes ~2 minutes to build
+1. Fork https://github.com/FCP-INDI/fcp-indi.github.com
+1. In your fork's settings, set the GitHub Pages `source` to `master` branch
+    ![GitHub Pages settings example screenshot](./images/github-pages-settings-example.png)
+1. Add your project on CircleCI
+1. Merge your draft / work-in-progress into your fork's `source` branch. Make sure you push to your fork and not the main repository's `source` branch.
+1. Your fork will publish at `https://[your_GitHub_username].github.io/fcp-indi.github.com/`.
+
+<a id="markdown-build-locally-c-pac-≥-v180" name="build-locally-c-pac-≥-v180"></a>
+#### Build locally (C-PAC ≥ v1.8.0)
+This documentation aspires to rely on a [single source of truth](https://en.wikipedia.org/wiki/Single_source_of_truth) where possible.  To this end, building this documentation requires an installation of the version of [C-PAC](https://github.com/FCP-INDI/C-PAC) that is being documented.
+
+Steps to build this documentation locally:
+1. Clone this repository.
+1. _(optional)_ <details><summary>Locally replicate the step "👊 Running cpac commands" from [.circleci/config](./.circleci/config) to generate [cpac](https://pypi.org/project/cpac/) usage strings.</summary>
+    Either perform this "👊 Running cpac commands" step in a separate Python environment or uninstall cpac after generating the usage string(s).
+    1. _(optional)_ Create an environment for cpac and activate this environment.
+    1. `pip install cpac`
+    1. If you don't have a local container for the version of C-PAC you're documenting, `cpac pull` to download the latest or `cpac pull --tag $TAG` to pull a specific version.
+    1. Generate ReStructuredText documents with cpac usage strings:
+       ```BASH
+        mkdir -p docs/_sources/user/cpac
+        printf ".. code-block:: console\n\n   $ cpac --help\n\n" > docs/_sources/user/cpac/help.rst
+        cpac --help | sed -e "s/.*/   &/" >> docs/_sources/user/cpac/help.rst
+        mkdir -p docs/_sources/user/run
+        printf "Usage: cpac run\n\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\n.. code-block:: console\n\n   $ cpac run --help\n\n" > docs/_sources/user/run/help.rst
+        cpac run --help | sed -e "s/.*/   &/" >> docs/_sources/user/run/help.rst
+        mkdir -p docs/_sources/user/utils
+        printf "Usage: cpac utils\n\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\n.. code-block:: console\n\n   $ cpac utils --help\n\n" > docs/_sources/user/utils/help.rst
+        cpac utils --help | sed -e "s/.*/   &/" >> docs/_sources/user/utils/help.rst
+        ```
+    1. `deactivate` your cpac environment if you used a separate environment or `pip uninstall cpac`.
+    </details>
+1. Locally install [C-PAC](https://github.com/FCP-INDI/C-PAC) from source.
+1. Run `./bin/build $VERSION` where `$VERSION` is the version to build (`nightly`, `latest`, or [<span title='Semantic Versioning'>semver</span>](https://semver.org/) for production, but this string can be anything you want locally). ![example version](./images/example_version.png)
+
+<a id="markdown-flowcharts" name="flowcharts"></a>
 ## Flowcharts
 
 - SVGs exported from Lucidchart have scaling coded in in `width` and `height` XML attributes. Add the XML attributes `preserveAspectRatio="xMinYMin meet"` and `viewBox` to the SVG element in the actual SVG files:
@@ -64,6 +119,7 @@ where `{width}` and `{height}` are the values already present in the existing `w
     <object data="../_static/path/to/chart.svg" type="image/svg+xml"></object>
 ```
 
+<a id="markdown-references-and-citations" name="references-and-citations"></a>
 ## References and citations
 
 [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/) is installed and configured. This extension creates links between the citations and the reference in the reference list and formats citations in referenced BibTeX files using built-in or [custom styles](https://github.com/FCP-INDI/fcp-indi.github.com/blob/source/docs/_sources/references/style.py). To use this Sphinx extension, 
@@ -114,6 +170,7 @@ The rendered file should look something like
 > 
 > <a name="ref1" href="#backref1">[1]</a> Craddock, C., Sikka, S., Cheung, B., Khanuja, R., Ghosh, S. S., Yan, C., Li, Q., Lurie, D., Vogelstein, J., Burns, R., Colcombe, S., Mennes, M., Kelly, C., Di Martino, A., Castellanos, F. X., and Milham, M. 2013. [Towards automated analysis of connectomes: the Configurable Pipeline for the Analysis of Connectomes (C-PAC).](http://www.frontiersin.org/neuroinformatics/10.3389/conf.fninf.2013.09.00042/full) *Frontiers in neuroinformatics* 42. doi:[10.3389/conf.fninf.2013.09.00042](https://dx.doi.org/10.3389/conf.fninf.2013.09.00042)
 
+<a id="markdown-environment-notes" name="environment-notes"></a>
 ## Environment notes
 * Because [C-PAC](https://github.com/FCP-INDI/C-PAC.git) and [cpac](https://github.com/FCP-INDI/cpac.git) have conflicting commandline commands, we first run any `cpac` commands in a virtual environment and spoof the `command-output` directive with `code-block` like 
    ```RST

bin/build

@@ -1,3 +1,10 @@
 #!/bin/bash
 
+# link references
+CPAC_DIRECTORY=$(python -c "import os, CPAC; print(os.path.abspath(os.path.dirname(CPAC.__file__)))")
+ln ${CPAC_DIRECTORY}/resources/configs/1.7-1.8-nesting-mappings.yml docs/_sources/references/1.7-1.8-nesting-mappings.yml || true
+ln ${CPAC_DIRECTORY}/resources/configs/1.7-1.8-deprecations.yml docs/_sources/references/1.7-1.8-deprecations.yml || true
+ln ${CPAC_DIRECTORY}/resources/configs/default_pipeline.yml docs/_sources/references/default_pipeline.yml || true
+
+# build docs
 sphinx-build -b html docs/_sources docs/$1

docs/_sources/conf.py

@@ -27,7 +27,7 @@
 
 sys.path.append(os.path.dirname(__file__))
 
-from references import CPAC_DocsStyle
+from references import CPAC_DocsStyle  # noqa: E402
 
 register_plugin('pybtex.style.formatting', 'cpac_docs_style', CPAC_DocsStyle)
 

images/example_version.png

@@ -0,0 +1,9 @@
+m2r
+numpydoc
+PyGithub
+sphinx
+sphinxcontrib-bibtex<2.0
+sphinxcontrib-fulltoc
+sphinxcontrib-programoutput
+semver
+torch