Add basic documentation

.gitattributes

@@ -1 +1,3 @@
 *.gif filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.svg filter=lfs diff=lfs merge=lfs -text

.github/workflows/docs_pages_workflow.yml

@@ -12,7 +12,7 @@ jobs:
 
     steps:
 
-    - name: Prereqs
+    - name: Preparation
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run: |
@@ -21,7 +21,7 @@ jobs:
         git clone "https://token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" .
       shell: bash
 
-    - name: Execute script to build our documentation and update pages
+    - name: Build documentation and update Github Pages
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run: |

README.md

@@ -1,6 +1,8 @@
 # [NiBAx] The neuro-imaging brain aging chart
 
-**This software is under development!**
+| :construction:  This software and documentation is under development! Check out up-to-date documentation in [cbica.github.io/NiBAx/](https://cbica.github.io/NiBAx/)  :construction: |
+|-----------------------------------------|
+
 
 ![](NiBAx/resources/workflow.gif)
 

docs/_templates/layout.html

@@ -0,0 +1,14 @@
+{% extends "!layout.html" %}
+  {% block footer %} {{ super() }}
+
+  <style>
+    /* Sidebar header (and topbar for mobile) */
+    .wy-side-nav-search, .wy-nav-top {
+      background: #95b1c2;
+    }
+    /* Sidebar */
+    .wy-nav-side {
+      background: #363745;
+    }
+  </style>
+{% endblock %}

docs/buildDocs.sh

@@ -13,9 +13,16 @@ set -x
 ###################
 
 apt-get update
-apt-get -y install git rsync python3-sphinx python3-sphinx-rtd-theme python3-stemmer python3-git python3-pip python3-virtualenv python3-setuptools
-
-python3 -m pip install --upgrade rinohtype pygments
+apt-get -y install git git-lfs rsync python3-stemmer python3-git python3-pip \
+                   python3-virtualenv python3-setuptools zlib1g zlib1g-dev libjpeg-dev \
+                   python3-pandas python3-matplotlib python3-seaborn
+
+python3 -m pip install --upgrade docutils==0.16
+python3 -m pip install --upgrade rinohtype Pygments myst_parser sphinx_tabs \
+                                 sphinx_rtd_theme sphinx rst2pdf sphinx-autoapi \
+                                 sphinx_gallery
+
+git lfs install
 
 #####################
 # DECLARE VARIABLES #
@@ -132,14 +139,17 @@ If you are looking for documentation, please see:
 
  * https://cbica.github.io/NiBAx/
 EOF
- 
+
 # copy the resulting html pages built from sphinx above to our new git repo
 git add .
 
 # commit all the new files
 msg="Updating Docs for commit ${GITHUB_SHA} made on `date -d"@${SOURCE_DATE_EPOCH}" --iso-8601=seconds` from ${GITHUB_REF} by ${GITHUB_ACTOR}"
 git commit -am "${msg}"
 
+# convert LFS objects to binary files
+git lfs migrate export --yes --include "*.png,*.gif" --include-ref HEAD
+
 # overwrite the contents of the gh-pages branch on our github.com repo
 git push deploy gh-pages --force
 

docs/conf.py

@@ -19,14 +19,14 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'NiBAx'
+project = 'NiBAχ'
 copyright = '2022, CBICA, University of Pennsylvania'
 author = 'Ashish Singh'
 
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
-release = '1.0.0'
+release = '0.1'
 
 
 # -- General configuration ---------------------------------------------------
@@ -39,19 +39,27 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'myst_parser',
     'sphinx_rtd_theme',
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
+    'sphinx_tabs.tabs',
+    'rst2pdf.pdfbuilder',
+    'autoapi.extension',
+    'sphinx_gallery.gen_gallery',
 ]
 
+autoapi_dirs = ['../NiBAx']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = ['.rst', '.md']
+source_suffix = {'.rst': 'restructuredtext',
+                 '.txt': 'markdown'}
 #source_suffix = '.rst'
 
 # The master toctree document.
@@ -85,13 +93,18 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'logo_only': True,
+    'display_version': True,
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_logo = "contents/images/NiBAx.png"
+
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
@@ -155,7 +168,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, 'NiBAx', 'NiBAx Documentation',
-     author, 'NiBAx', 'One line description of project.',
+     author, 'Ahmed Abdulkadir', 'The neuro-imaging brain aging chart',
      'Miscellaneous'),
 ]