📚 C-PAC Python package (#219)

.circleci/config.yml

@@ -16,11 +16,29 @@ jobs:
             pip install --user -r https://raw.githubusercontent.com/FCP-INDI/C-PAC/develop/requirements.txt
             pip install --user git+https://github.com/FCP-INDI/C-PAC.git sphinx m2r numpydoc PyGithub sphinxcontrib-programoutput
             git clone https://github.com/FCP-INDI/C-PAC.git /build/C-PAC
+            python -m venv ~/simple
+            source ~/simple/bin/activate
+            pip install cpac
+            deactivate
+      - setup_remote_docker
       - run:
-          name: Build docs
+          name: Run cpac commands
           command: |
-            ./bin/build
-
+            source ~/simple/bin/activate
+            cpac run --help
+            mkdir -p docs/user/_sources/cpac
+            printf ".. code-block:: console\n\n   $ cpac --help\n\n" > docs/user/_sources/cpac/help.txt
+            cpac --help | sed -e "s/.*/   &/" >> docs/user/_sources/cpac/help.txt
+            mkdir -p docs/user/_sources/run
+            printf "Usage: cpac run\n\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\n.. code-block:: console\n\n   $ cpac run --help\n\n" > docs/user/_sources/run/help.txt
+            cpac run --help | sed -e "s/.*/   &/" >> docs/user/_sources/run/help.txt
+            mkdir -p docs/user/_sources/utils
+            printf "Usage: cpac utils\n\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\n.. code-block:: console\n\n   $ cpac utils --help\n\n" > docs/user/_sources/utils/help.txt
+            cpac utils --help | sed -e "s/.*/   &/" >> docs/user/_sources/utils/help.txt
+            deactivate
+      - run:
+          name: Build docs
+          command: ./bin/build
       - run:
           name: Configure git user
           command: |

CONTRIBUTING.md

@@ -46,6 +46,15 @@ where `{width}` and `{height}` are the values already present in the existing `w
 ```
 
 ## Environment notes
-* :snake: Until [C-PAC Python 2 → 3 conversion](https://github.com/FCP-INDI/C-PAC/issues/1114) is complete, these docs require Python 2.7 to build.
+* 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
+   .. code-block:: console
+
+       cpac run --help
+       
+   .. program-output:: cpac_py run --help
+      :shell:
+      :ellipsis: 0,9
+   ```
 * :heavy_plus_sign: Check [`.circleci/config.yml`](https://github.com/FCP-INDI/fcp-indi.github.com/blob/source/.circleci/config.yml) of the branch you're working from for build dependencies.
 * :octocat: Set an environment variable `GITHUBTOKEN` to a [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) to increase [your API rate limit](https://developer.github.com/v3/#rate-limiting) from 60 to 5000 requests per hour (for getting [release notes from GitHub](https://github.com/FCP-INDI/C-PAC/releases)).

docs/user/appendix.html

@@ -48,7 +48,7 @@ <h3>Before You Start<a class="headerlink" href="#before-you-start" title="Permal
 <p><strong>WAIT! Installing C-PAC is not required, and is an option for those who want to maintain their own installation, often on a server or cluster. For a faster way to get started:</strong></p>
 <p>C-PAC can be run without installing through any of these three options:</p>
 <ul class="simple">
-<li>With a Docker container</li>
+<li>With a Docker or Singularity container (optionally with <a class="reference internal" href="cpac"><span class="doc">a simple Python commandline interface</span></a>)</li>
 <li>On the Amazon AWS Cloud</li>
 <li>Through OpenNeuro</li>
 </ul>
@@ -82,15 +82,18 @@ <h4>A Note About the *nix Command Line<a class="headerlink" href="#a-note-about-
 </div>
 <div class="section" id="overview">
 <h3>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h3>
-<p>If you are using Ubuntu (version 12/14) you can download  and run <a class="reference external" href="https://github.com/FCP-INDI/C-PAC/blob/master/scripts/cpac_install.sh?raw=true">cpac_install.sh</a> with the following terminal commands as root:</p>
+<p>If you are using Ubuntu (version 12/14) you can download and run <a class="reference external" href="https://github.com/FCP-INDI/C-PAC/blob/master/scripts/cpac_install.sh?raw=true">cpac_install.sh</a> with the following terminal commands as root:</p>
 <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">wget https://github.com/FCP-INDI/C-PAC/blob/master/scripts/cpac_install.sh?raw=true</span>
 <span class="go">mv cpac_install.sh?raw=true cpac_install.sh</span>
 <span class="go">chmod +x cpac_install.sh</span>
 <span class="go">sudo ./cpac_install.sh -r</span>
 </pre></div>
 </div>
 <p>This will install all of the prerequisites and resources listed below. If you have previously installed versions of these, they will not be reinstalled, and the script will not check the release version to match the requirements of C-PAC.</p>
-<p><strong>Note</strong>: This script is intended for Ubuntu Linux 12/14,  but it may work for older releases of Ubuntu.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This script is intended for Ubuntu Linux 12/14,  but it may work for older releases of Ubuntu.</p>
+</div>
 <p><strong>For other operating systems</strong>, this page will guide you through the following C-PAC installation steps:</p>
 <ul class="simple">
 <li>Installing the required system-level dependencies</li>
@@ -162,8 +165,15 @@ <h5>OS-Specific Instructions<a class="headerlink" href="#os-specific-instruction
 </div>
 <div class="section" id="installing-python-dependencies">
 <h4>Installing Python Dependencies<a class="headerlink" href="#installing-python-dependencies" title="Permalink to this headline">¶</a></h4>
-<p>Please ensure that you are using Python 2.7 and above, but not Python 3 (since it is not backwards-compatible). Though many computers come with Python pre-installed, C-PAC relies on a number of special-purpose packages, which are listed below. Packages with an asterisk can be installed through <a class="reference external" href="https://pythonhosted.org/setuptools/easy_install.html">easy_install</a> or pip.  Installing <a class="reference external" href="https://store.continuum.io/cshop/anaconda/">Anaconda</a> (<strong>64-bit version only</strong>), <a class="reference external" href="http://conda.pydata.org/miniconda.html">Miniconda</a> or  <a class="reference external" href="https://www.enthought.com/products/canopy/">Enthought Canopy</a> and using a package manager can simplify installation greatly.  Instructions for Miniconda are given below.</p>
-<p>Note: Specific maximum versions are required for the following dependencies. C-PAC is currently (temporarily) not compatible with versions past the following:</p>
+<p>Please ensure that you are using Python 3.6 and above. Though many computers come with Python pre-installed, C-PAC relies on a number of special-purpose packages, which are listed below. Packages with an asterisk can be installed through <a class="reference external" href="https://pythonhosted.org/setuptools/easy_install.html">easy_install</a> or pip.  Installing <a class="reference external" href="https://store.continuum.io/cshop/anaconda/">Anaconda</a> (<strong>64-bit version only</strong>), <a class="reference external" href="http://conda.pydata.org/miniconda.html">Miniconda</a> or  <a class="reference external" href="https://www.enthought.com/products/canopy/">Enthought Canopy</a> and using a package manager can simplify installation greatly.  Instructions for Miniconda are given below.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last"><a class="reference internal" href="cpac"><span class="doc">cpac (the simple Python commandline interface)</span></a> and a local installation of C-PAC will conflict if installed in the same environment because both use the same commandline command (<code class="docutils literal notranslate"><span class="pre">cpac</span></code>).</p>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Specific maximum versions are required for the following dependencies. C-PAC is currently (temporarily) not compatible with versions past the following:</p>
+</div>
 <ul class="simple">
 <li><a class="reference external" href="http://nipype.readthedocs.io/en/latest/">Nipype</a> - version 1.1.2</li>
 <li><a class="reference external" href="http://networkx.lanl.gov/">NetworkX</a> - version 1.11</li>
@@ -259,8 +269,14 @@ <h4>Installing AFNI and FSL<a class="headerlink" href="#installing-afni-and-fsl"
 </pre></div>
 </div>
 <p>If you open a new shell and type <cite>afni</cite> the AFNI console should now appear.  If not, double-check the lines added to <cite>/etc/bash.bashrc</cite> for typos and make sure that <cite>/opt/afni</cite> contains the AFNI commands.</p>
-<p><strong>Note:</strong> Regarding the Neurodebian repository: We have encountered compatibility issues in the past with the Neurodebian binary for AFNI.  For this reason, it is suggested that you follow the installation instructions above or the instructions from the AFNI homepage.</p>
-<p><strong>Note:</strong> On some Ubuntu systems, AFNI can have trouble locating the libgsl.so.0 software library required for some of their tools (3dSkullStrip, and 3dHist). If you experience an error trying to run any of these tools, first attempt to re-install AFNI via the instructions on the AFNI homepage. If this does not resolve the issue, another solution involves locating your system’s GSL library and re-configuring:</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Regarding the Neurodebian repository: We have encountered compatibility issues in the past with the Neurodebian binary for AFNI.  For this reason, it is suggested that you follow the installation instructions above or the instructions from the AFNI homepage.</p>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">On some Ubuntu systems, AFNI can have trouble locating the libgsl.so.0 software library required for some of their tools (3dSkullStrip, and 3dHist). If you experience an error trying to run any of these tools, first attempt to re-install AFNI via the instructions on the AFNI homepage. If this does not resolve the issue, another solution involves locating your system’s GSL library and re-configuring:</p>
+</div>
 <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">locate libgsl</span>
 <span class="go">ldconfig -n /path/to/libgsl</span>
 </pre></div>
@@ -425,18 +441,23 @@ <h4>Installing C-PAC<a class="headerlink" href="#id4" title="Permalink to this h
 <h5>Testing Your C-PAC Installation<a class="headerlink" href="#testing-your-c-pac-installation" title="Permalink to this headline">¶</a></h5>
 <p>In a new terminal window, open iPython (or Python) and enter the command <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">CPAC</span></code>. If installation was successful, this will execute without an error and present you with a blank new line. If you encounter an error (e.g. <code class="docutils literal notranslate"><span class="pre">no</span> <span class="pre">module</span> <span class="pre">named</span> <span class="pre">C-PAC</span></code>), try re-running the C-PAC install command above. If this does not work, see the <a class="reference internal" href="help"><span class="doc">Troubleshooting and Help Page</span></a>.  Note that if you do not open a new terminal window and are still within the C-PAC installation directory (‘C-PAC’), you may encounter errors that can be alleviated by leaving the ‘C-PAC’ directory.</p>
 <p>Once you are able to successfully <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">CPAC</span></code> it is safe to delete any setup files downloaded during the install process (e.g. Nipype and C-PAC downloads, FSL install scripts, etc.), as they are no longer needed.</p>
-<p><strong>Note:</strong> The test process described here only acts to confirm that the C-PAC python package has been correctly installed. To fully test C-PAC on your system, please see the <a class="reference internal" href="benchmark"><span class="doc">Benchmark Page</span></a>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The test process described here only acts to confirm that the C-PAC python package (the core package, not <a class="reference internal" href="cpac"><span class="doc">the simple Python commandline interface with the same name</span></a>) has been correctly installed. To fully test C-PAC on your system, please see the <a class="reference internal" href="benchmark"><span class="doc">Benchmark Page</span></a>.</p>
+</div>
 </div>
 </div>
 <div class="section" id="updating-c-pac">
 <h4>Updating C-PAC<a class="headerlink" href="#updating-c-pac" title="Permalink to this headline">¶</a></h4>
 <p>C-PAC is being actively developed, and new versions (containing bug fixes and new features) are often released. To update to the latest version, simply download it from the <a class="reference external" href="http://fcp-indi.github.com/">C-PAC Homepage</a> and repeat the instructions in the <cite>Installing C-PAC</cite> section above. A list of previous versions and the changes they contain is available on the <a class="reference internal" href="rnotes"><span class="doc">Release Notes Page</span></a>.</p>
-<p><strong>Note: If you are using Anaconda/Miniconda you may also use the following command (replacing ‘cpac’ with your environment name) to remove an old environment before creating a new environment to replace it.</strong></p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
 <blockquote>
-<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">conda remove --all -n cpac</span>
+<div>If you are using Anaconda/Miniconda you may also use the following command (replacing ‘cpac’ with your environment name) to remove an old environment before creating a new environment to replace it.**</div></blockquote>
+<div class="last highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">conda remove --all -n cpac</span>
 </pre></div>
 </div>
-</div></blockquote>
+</div>
 </div>
 <div class="section" id="running-c-pac-without-installing">
 <h4>Running C-PAC Without Installing<a class="headerlink" href="#running-c-pac-without-installing" title="Permalink to this headline">¶</a></h4>
@@ -445,6 +466,10 @@ <h4>Running C-PAC Without Installing<a class="headerlink" href="#running-c-pac-w
 <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">python setup.py build_ext --inplace</span>
 </pre></div>
 </div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Unfortunately, it is not possible at this time to use the C-PAC GUI without installing C-PAC.</p>
+</div>
 </div>
 </div>
 </div>