Skip to content

Commit d5a668e

Browse files
committed
📚 Specify local build instructions are for CPAC ≥ v1.8.0
1 parent 42712c9 commit d5a668e

File tree

1 file changed

+13
-2
lines changed

1 file changed

+13
-2
lines changed

CONTRIBUTING.md

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,27 @@
77
- [Guidelines](#guidelines)
88
- [Building](#building)
99
- [Let CircleCI build your drafts / works-in-progress](#let-circleci-build-your-drafts--works-in-progress)
10-
- [Build locally](#build-locally)
10+
- [Build locally (C-PAC ≥ v1.8.0)](#build-locally-c-pac-≥-v180)
1111
- [Flowcharts](#flowcharts)
1212
- [References and citations](#references-and-citations)
1313
- [Environment notes](#environment-notes)
1414

1515
<!-- /TOC -->
1616

17+
<a id="markdown-branches" name="branches"></a>
1718
## Branches
1819

1920
Please, always base changes on the `source` branch. `master` branch will be overwritten by the CI deployment.
2021

22+
<a id="markdown-versions" name="versions"></a>
2123
### Versions
2224

25+
<a id="markdown-nightly" name="nightly"></a>
2326
#### `nightly`
2427

2528
Pushes to `source` will rebuild docs at https://fcp-indi.github.io/docs/nightly
2629

30+
<a id="markdown-c-pac-release-tags" name="c-pac-release-tags"></a>
2731
#### C-PAC release tags
2832
Tags in the format `v.*-source` will build docs for the given version.
2933

@@ -37,6 +41,7 @@ Steps to build a release:
3741
5. (Force) push to the remote tag (`git push origin v`version`-source`).
3842
6. CircleCI should deploy the versioned documentation. If the version tag is the newest, it should also overwrite `latest` with these documents.
3943

44+
<a id="markdown-guidelines" name="guidelines"></a>
4045
## Guidelines
4146

4247
- 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.
@@ -54,8 +59,10 @@ Steps to build a release:
5459
"
5560
```
5661

62+
<a id="markdown-building" name="building"></a>
5763
### Building
5864

65+
<a id="markdown-let-circleci-build-your-drafts--works-in-progress" name="let-circleci-build-your-drafts--works-in-progress"></a>
5966
#### Let CircleCI build your drafts / works-in-progress
6067
* Build environment will match actual docs build environment
6168
* CircleCI takes ~2 minutes to build
@@ -66,7 +73,8 @@ Steps to build a release:
6673
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.
6774
1. Your fork will publish at `https://[your_GitHub_username].github.io/fcp-indi.github.com/`.
6875

69-
#### Build locally
76+
<a id="markdown-build-locally-c-pac-≥-v180" name="build-locally-c-pac-≥-v180"></a>
77+
#### Build locally (C-PAC ≥ v1.8.0)
7078
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.
7179

7280
Steps to build this documentation locally:
@@ -93,6 +101,7 @@ Steps to build this documentation locally:
93101
1. Locally install [C-PAC](https://github.com/FCP-INDI/C-PAC) from source.
94102
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)
95103

104+
<a id="markdown-flowcharts" name="flowcharts"></a>
96105
## Flowcharts
97106

98107
- 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:
@@ -110,6 +119,7 @@ where `{width}` and `{height}` are the values already present in the existing `w
110119
<object data="../_static/path/to/chart.svg" type="image/svg+xml"></object>
111120
```
112121

122+
<a id="markdown-references-and-citations" name="references-and-citations"></a>
113123
## References and citations
114124

115125
[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,
@@ -160,6 +170,7 @@ The rendered file should look something like
160170
>
161171
> <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)
162172

173+
<a id="markdown-environment-notes" name="environment-notes"></a>
163174
## Environment notes
164175
* 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
165176
```RST

0 commit comments

Comments
 (0)