feat: Refactored code, added CI for docs.

BREAKING CHANGE: Re-organised folder structure.

.github/workflows/push-main.yml → .github/workflows/pypi-publish.yml

@@ -1,25 +1,14 @@
-name: Release
+name: PyPI publish
 on:
-  push:
-    branches:
-      - main
+  release:
+    types: [ published ]
 
 jobs:
-  release:
-    name: release
+  pypi-publish:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
-        with:
-          cache: npm
-          node-version: 16
-      - run: npm install
-      - run: npx semantic-release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Set up Python
+      - name: Setup Python
         uses: actions/setup-python@v2
         with:
           python-version: '3.6'
@@ -33,4 +22,4 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
         run: |
           python setup.py sdist bdist_wheel
-          twine upload dist/*
+          twine upload dist/*

.github/workflows/semantic-release.yml

@@ -0,0 +1,63 @@
+name: Semantic release
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  semantic-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          cache: npm
+          node-version: 16
+      - run: npm install
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+
+  documentation:
+    runs-on: ubuntu-latest
+    needs: ['semantic-release']
+    steps:
+      - uses: actions/setup-python@v2
+        with:
+          python-version: '3.8'
+
+      # Checkout the main branch to /main
+      - uses: actions/checkout@v2
+        with:
+          path: main
+
+      # Checkout the GitHub pages branch to /gh-pages
+      - uses: actions/checkout@v2
+        with:
+          ref: gh-pages
+          path: gh-pages
+
+      - name: Install Sphinx requirements
+        working-directory: ${{ github.workspace }}/main/docs
+        run: |
+          sudo apt-get update -y
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt
+
+      - name: Build documentation
+        working-directory: ${{ github.workspace }}/main/docs
+        run: make html
+
+      - name: Move documentation
+        run: |
+          touch main/docs/build/html/.nojekyll
+          cp -a main/docs/build/html/. gh-pages/
+
+      - name: Upload documentation
+        working-directory: ${{ github.workspace }}/gh-pages
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git add --all
+          git diff-index --quiet HEAD || git commit -m "docs update" -a
+          git push

.releaserc

@@ -20,7 +20,8 @@
     [
       "@semantic-release/changelog",
       {
-        "changelogFile": "CHANGELOG.md"
+        "changelogFile": "CHANGELOG.md",
+        "changelogTitle": "# Changelog"
       }
     ],
   [

README.md

@@ -1,2 +1,17 @@
 # magna
-The magna CLI package is a collection of commands that I frequently use in bioinformatics and day-to-day life.
+
+[![PyPI](https://img.shields.io/pypi/v/magna.svg)](https://pypi.python.org/pypi/magna)
+
+Magna is a collection of bioinformatic datasets and utilities I use in my everyday life.
+
+This has been written with the intention of personal use, but feel free to use/contribute.
+
+**Documentation:** [https://aaronmussig.github.io/magna/](https://aaronmussig.github.io/magna/)
+
+
+## Contributing
+
+This project uses [Semantic Versioning](http://semver.org/) and [Conventional Commits](https://conventionalcommits.org/)
+to automatically generate release notes using [Semantic Release](https://semantic-release.gitbook.io/semantic-release/).
+
+Please ensure that your commits are property formatted.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx-rtd-theme ~= 1.0.0
+sphinx ~= 4.4.0
+sphinx-autodoc-typehints ~= 1.12.0
+myst-parser ~= 0.16.1

docs/source/_static/css/custom.css

@@ -0,0 +1,13 @@
+@import 'theme.css';
+
+.wy-nav-content {
+    max-width: 100% !important;
+}
+
+.wy-side-nav-search {
+    background-color: #2a518f !important;
+}
+
+.rst-content img {
+    margin-right: 5px;
+}

docs/source/changelog.md

@@ -0,0 +1 @@
+../../CHANGELOG.md

docs/source/conf.py

@@ -0,0 +1,109 @@
+import os
+import sys
+from datetime import datetime
+import sphinx_rtd_theme
+
+sys.path.insert(0, os.path.abspath('../..'))
+from magna import __author__, __version__, __title__, __url__
+
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+
+# The full version, including alpha/beta/rc tags
+release = __version__
+project = __title__
+copyright = f'{datetime.now().year}, {__author__}'
+author = __author__
+
+# The full version, including alpha/beta/rc tags
+version = __version__
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+github_url = __url__
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon',
+              'sphinx_rtd_theme', 'sphinx_autodoc_typehints',
+              'myst_parser']
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
+# autodoc_typehints = 'None'
+autodoc_typehints_format = 'short'
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+
+html_theme_options = {# 'analytics_id': 'G-XXXXXXXXXX',  #  Provided by Google in your dashboard
+    'analytics_anonymize_ip': False, 'logo_only': False, 'display_version': True,
+    'prev_next_buttons_location': 'bottom', 'style_external_links': False, 'vcs_pageview_mode': '',
+    'style_nav_header_background': 'white', # Toc options
+    'collapse_navigation': True, 'sticky_navigation': True, 'navigation_depth': 4, 'includehidden': True,
+    'titles_only': False}
+
+#
+html_theme = 'sphinx_rtd_theme'
+
+# 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_style = 'css/custom.css'
+
+html_context = {'display_github': True, 'github_user': 'aaronmussig', 'github_repo': 'magna',
+    'github_version': 'master/docs/source/'}
+
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md': 'markdown',
+}

docs/source/gtdb/enums.rst

@@ -0,0 +1,8 @@
+*****
+Enums
+*****
+
+.. autoclass:: magna.gtdb.enums.GtdbRelease
+    :members:
+    :undoc-members:
+    :member-order: bysource

docs/source/gtdb/genome.rst

@@ -0,0 +1,11 @@
+******
+Genome
+******
+
+.. autoclass:: magna.gtdb.genome.Genome
+    :members:
+
+
+.. autoclass:: magna.gtdb.genome.GenomeDirs
+    :members:
+    :special-members: __init__

docs/source/gtdb/metadata.rst

@@ -0,0 +1,33 @@
+********
+Metadata
+********
+
+.. autoclass:: magna.gtdb.metadata.GtdbMetadata
+   :members:
+
+
+Release 95
+----------
+
+.. autoclass:: magna.gtdb.metadata.GtdbMetadataR95
+    :members:
+
+.. autoclass:: magna.gtdb.metadata.GtdbMetadataR95Arc
+    :show-inheritance:
+
+.. autoclass:: magna.gtdb.metadata.GtdbMetadataR95Bac
+    :show-inheritance:
+
+
+
+Release 202
+-----------
+
+.. autoclass:: magna.gtdb.metadata.GtdbMetadataR202
+    :members:
+
+.. autoclass:: magna.gtdb.metadata.GtdbMetadataR202Arc
+    :show-inheritance:
+
+.. autoclass:: magna.gtdb.metadata.GtdbMetadataR202Bac
+    :show-inheritance:

docs/source/gtdb/tree.rst

@@ -0,0 +1,26 @@
+****
+Tree
+****
+
+.. autoclass:: magna.gtdb.tree.GtdbTree
+   :members:
+
+
+Release 95
+----------
+
+.. autoclass:: magna.gtdb.tree.GtdbTreeR95Arc
+    :show-inheritance:
+
+.. autoclass:: magna.gtdb.tree.GtdbTreeR95Bac
+    :show-inheritance:
+
+
+Release 202
+-----------
+
+.. autoclass:: magna.gtdb.tree.GtdbTreeR202Arc
+    :show-inheritance:
+
+.. autoclass:: magna.gtdb.tree.GtdbTreeR202Bac
+    :show-inheritance:

docs/source/gunc/index.rst

@@ -0,0 +1,24 @@
+****
+GUNC
+****
+
+GTDB R95 reference DB
+---------------------
+
+Note: The following methods have source data that is not publicly available:
+
+.. autofunction:: magna.gunc.gunc_max_css_scores_gtdb_r95
+
+.. autofunction:: magna.gunc.gunc_contig_assignment_gtdb_r95
+
+.. autofunction:: magna.gunc.gunc_all_levels_gtdb_r95
+
+
+Progenes reference DB
+---------------------
+
+.. autoclass:: magna.gunc.GuncMaxCssScores
+    :members:
+
+.. autoclass:: magna.gunc.GuncAllScores
+    :members: