Skip to content

Latest commit

 

History

History
205 lines (162 loc) · 12.1 KB

CONTRIBUTING.md

File metadata and controls

205 lines (162 loc) · 12.1 KB
Raw

Branches

Please, always base changes on the source branch. main branch will be overwritten by the CI deployment.

Versions

nightly

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

C-PAC release tags

Tags in the format v.*-source will build docs for the given version.

If a matching version tag doesn't exist in https://github.com/FCP-INDI/C-PAC/tags, the build should fail.

Steps to build a release:

  1. Checkout a commit from the source from a time appropriate for documentation for the branch being built/rebuilt.
  2. If you need to make changes, create a branch (git switch -c or git checkout -b).
  3. Make any changes you need for the specific version.
  4. Tag the commit that's ready to build (git tag vversion-source)
  5. (Force) push to the remote tag (git push origin vversion-source).
  6. CircleCI should deploy the versioned documentation. If the version tag is the newest, it should also overwrite latest with these documents.

Guidelines

  • Only write a document once, and liberally use the reStructured Text .. include:: directive to include that document where appropriate.
  • Use absolute paths for .. include::s. That way the path will resolve correctly regardless of differences in nesting levels.
  • Include any source documents that you want built in at least one toctree. Use the :hidden: option if you don't want it linked in an actual table of contents in the document with the toctree.
  • Use consistent section title indicators throughout a sourcetree. fcp-indi.github.io/docs/user currently has the following hierarchy (top to bottom): 
    =
^
-
*
#
`
'
"

Building

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.io
  2. In your fork's settings, set the GitHub Pages source to main branch GitHub Pages settings example screenshot
  3. Add your project on CircleCI
  4. 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.
  5. Your fork will publish at https://[your_GitHub_username].github.io/fcp-indi.github.io/.

Build locally (C-PAC ≥ v1.8.0)

This documentation aspires to rely on a single source of truth where possible. To this end, building this documentation requires an installation of the version of C-PAC that is being documented.

Steps to build this documentation locally:

  1. Clone this repository.
  2. (optional)
    Locally replicate the step "👊 Running cpac commands" from .circleci/config to generate cpac usage strings. 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.
    2. pip install cpac
    3. 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.
    4. Generate ReStructuredText documents with cpac usage strings: 
       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
    5. deactivate your cpac environment if you used a separate environment or pip uninstall cpac.
  3. Locally install C-PAC from source.
  4. Run ./bin/build $VERSION where $VERSION is the version to build (nightly, latest, or semver for production, but this string can be anything you want locally). example version

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:
<svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 {width} {height}"></svg>

where {width} and {height} are the values already present in the existing width and height XML attributes.

  • Embed SVGs with the raw:: html directive to preserve hyperlinks. Since the svg-flowchart container scales SVGs to the page width, add a link below to view them at their original scale:
.. container:: svg-flowchart

    .. raw:: html
        :file: ../_static/path/to/chart.svg

    `Open image <../_static/path/to/chart.svg>`_

Tutorials

See FCP-INDI/C-PAC_tutorials/CONTRIBUTING.md for how to contribute tutorials. Add them to the TOC tree in that repository or in any TOC tree in this repository with a relative path beginning /user/tutorials/ (e.g., /user/tutorials/observed_usage for observed_usage.ipynb).

References and citations

sphinxcontrib-bibtex 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. To use this Sphinx extension,

  1. Include your references in a BibTeX file. Unless you have a speficic reason to use a separate file, that BibTeX file should be docs/_sources/references/references.bib.
  2. Using the key (the text between the opening { and the first , in a BibTeX entry) use the ReStructuredText syntax :cite:`key` to cite your reference in a ReStructuredText file.
  3. Include a .. bibliography:: directive somewhere on any page that you want to use this extension to format references and create two-way links between the references and citations. Both :cite: and .. bibliography:: need to be rendered on the same page for the links to generate. You can list uncited references by listing their BibTeX keys explicilty
  4. If you will (or might) use more than one .. bibliography:: directive on a single rendered page (including .. include:: directives), choose a prefix for the keys and include that prefix in both the :cite: role (like :cite:`prefix-key`) and the bibliography directive (like :keyprefix: prefix-).
  5. If you want to include a header over a reference list, use the .. rubric:: directive above its .. bibliography directive.
  6. If the entry type (e.g., book, article, misc) of any of the entries in your BibTeX file(s) is not included in docs/_sources/references/style.py, add a get_{entry_type}_template Pybtex method to CPAC_DocsStyle.

For example, if you have a BibTeX file called cpac_citation.bib that contains

@ARTICLE{cpac2013,
    AUTHOR={Craddock, Cameron  and  Sikka, Sharad  and  Cheung, Brian  and  Khanuja, Ranjeet  and  Ghosh, Satrajit S
        and Yan, Chaogan  and  Li, Qingyang  and  Lurie, Daniel  and  Vogelstein, Joshua  and  Burns, Randal  and
        Colcombe, Stanley  and  Mennes, Maarten  and  Kelly, Clare  and  Di Martino, Adriana  and  Castellanos,
        Francisco Xavier  and  Milham, Michael},
    TITLE={Towards Automated Analysis of Connectomes: The {Configurable Pipeline for the Analysis of Connectomes (C-PAC)}},
    JOURNAL={Frontiers in Neuroinformatics},
    YEAR={2013},
    NUMBER={42},
    URL={http://www.frontiersin.org/neuroinformatics/10.3389/conf.fninf.2013.09.00042/full},
    DOI={10.3389/conf.fninf.2013.09.00042},
    ISSN={1662-5196}
}

If you include

To cite C-PAC, use :cite:`cite-example-cpac2013`.

.. rubric Cite C-PAC

.. bibliography::
   :cited:
   :keyprefix: cite-example-

The rendered file should look something like

To cite C-PAC, use [1].

Cite C-PAC

[1] 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). Frontiers in neuroinformatics 42. doi:10.3389/conf.fninf.2013.09.00042

Or

.. bibliography::
   :cited:
   
   cpac2013

to generate the bibliography entry without the citation.

Environment notes

  • Because C-PAC and cpac have conflicting commandline commands, we first run any cpac commands in a virtual environment and spoof the command-output directive with code-block like 
    .. code-block:: console

    cpac run --help
    
.. program-output:: cpac_py run --help
   :shell:
   :ellipsis: 0,9
  • ➕ Check .circleci/config.yml of the branch you're working from for build dependencies.
  • :octocat: Set an environment variable GITHUBTOKEN to a personal access token to increase your API rate limit from 60 to 5000 requests per hour (for getting release notes from GitHub).