docs: make sphinx docs (#182)

* also update type signatures for sphinx autodocs

.github/workflows/github-actions.yml

@@ -43,3 +43,13 @@ jobs:
 
       - run: pipenv run flake8
       - run: pipenv run pytest tests/
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: ammaraskar/sphinx-action@master
+        with:
+          pre-build-command: "python3 -m pip install .; python3 -m pip install sphinx_autodoc_typehints"
+          docs-folder: "docs/"
+

.gitignore

@@ -162,3 +162,6 @@ dynamodb_local_latest/*
 Pipfile.lock
 *.toml
 *.zip
+
+# documentation
+docs/build

Pipfile

@@ -24,3 +24,5 @@ flake8-docstrings = "*"
 pytest-cov = "*"
 mock = "*"
 ipykernel = "*"
+sphinx = "6.1.3"
+sphinx-autodoc-typehints = "1.22.0"

README.md

@@ -8,7 +8,7 @@ Services and guidelines for normalizing gene terms
 The Normalizer is available via PyPI:
 
 ```commandline
-pip install gene[dev]
+pip install gene-normalizer[dev]
 ```
 
 The `[dev]` argument tells pip to install packages to fulfill the dependencies of the `gene.etl` package.

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/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/api/api.rst

@@ -0,0 +1,10 @@
+API Reference
+=============
+
+.. toctree::
+
+    Query API<query_api>
+    Database Main API<database_api>
+    DynamoDB Handler API<dynamodb_api>
+    PostgreSQL Handler API<postgres_api>
+    Source ETL API<etl_api>

docs/source/api/database_api.rst

@@ -0,0 +1,7 @@
+Database API
+============
+
+.. automodule:: gene.database.database
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/api/dynamodb_api.rst

@@ -0,0 +1,8 @@
+DynamoDB Handler API
+=========================
+
+.. autoclass:: gene.database.dynamodb.DynamoDbDatabase
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

docs/source/api/etl_api.rst

@@ -0,0 +1,58 @@
+.. _etl-api:
+
+Source ETL API
+==============
+
+Base
+----
+
+.. autoclass:: gene.etl.base.Base
+   :members:
+   :undoc-members:
+
+
+NCBI
+----
+
+.. autoclass:: gene.etl.ncbi.NCBI
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+HGNC
+----
+
+.. autoclass:: gene.etl.hgnc.HGNC
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Ensembl
+-------
+
+.. autoclass:: gene.etl.ensembl.Ensembl
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Normalized Records
+------------------
+
+.. autoclass:: gene.etl.merge.Merge
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Chromosome Location
+-------------------------------
+
+.. autoclass:: gene.etl.vrs_locations.chromosome_location.ChromosomeLocation
+   :members:
+   :undoc-members:
+
+Sequence Location
+-----------------------------
+
+.. autoclass:: gene.etl.vrs_locations.sequence_location.SequenceLocation
+   :members:
+   :undoc-members:

docs/source/api/postgres_api.rst

@@ -0,0 +1,7 @@
+PostgreSQL Handler API
+=========================
+
+.. autoclass:: gene.database.postgresql.PostgresDatabase
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/api/query_api.rst

@@ -0,0 +1,14 @@
+.. _query-api:
+
+Query API
+=========
+
+.. autoclass:: gene.query.QueryHandler
+    :members:
+    :undoc-members:
+
+.. autoexception:: gene.query.InvalidParameterException
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

docs/source/conf.py

@@ -0,0 +1,49 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Gene Normalizer'
+copyright = '2023, VICC'
+author = 'VICC'
+
+
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx.ext.autodoc", "sphinx_autodoc_typehints", "sphinx.ext.linkcode"]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = []
+
+# -- autodoc things ----------------------------------------------------------
+import os  # noqa: E402
+import sys  # noqa: E402
+sys.path.insert(0, os.path.abspath("../../gene"))
+
+
+# -- get version -------------------------------------------------------------
+from gene import __version__  # noqa: E402
+version = __version__
+release = version
+
+# -- linkcode ----------------------------------------------------------------
+def linkcode_resolve(domain, info):
+    if domain != "py":
+        return None
+    if not info["module"]:
+        return None
+    filename = info["module"].replace(".", "/")
+    return f"https://github.com/cancervariants/gene-normalization/blob/main/{filename}.py"  # noqa: E501

docs/source/contributing.rst

@@ -0,0 +1,72 @@
+Contributing to the Gene Normalizer
+===================================
+
+Bug reports and feature requests
+--------------------------------
+
+Bugs and new feature requests can be submitted to the Gene Normalizer `issue tracker on GitHub <https://github.com/cancervariants/gene-normalization/issues>`_. See `this StackOverflow post <https://stackoverflow.com/help/minimal-reproducible-example>`_ for tips on how to craft a helpful bug report.
+
+Development prerequisites
+-------------------------
+For a development install, we recommend using Pipenv. See the `pipenv docs <https://pipenv-fork.readthedocs.io/en/latest/#install-pipenv-today>`_ for direction on installing Pipenv in your environment.
+
+Setup
+-----
+Clone the repository: ::
+
+    git clone https://github.com/cancervariants/gene-normalization
+    cd gene-normalization
+
+Then initialize the Pipenv environment: ::
+
+    pipenv update
+    pipenv install --dev
+    pipenv shell
+
+We use `pre-commit <https://pre-commit.com/#usage>`_ to run conformance tests before commits. This provides checks for:
+
+* Code style
+* Added large files
+* AWS credentials
+* Private keys
+
+Before your first commit, run: ::
+
+    pre-commit install
+
+When running the web server, enable hot-reloading on new code changes: ::
+
+    uvicorn gene.main:app --reload
+
+
+Style
+-----
+
+Code style is managed by `flake8 <https://github.com/PyCQA/flake8>`_ and should be checked via pre-commit hook before commits. Final QC is applied with GitHub Actions to every pull request.
+
+
+Tests
+-----
+
+Tests are executed with `pytest <https://docs.pytest.org/en/7.1.x/getting-started.html>`_: ::
+
+    pytest
+
+By default, tests will utilize an existing database, and won't load any new data. For test environments where this is unavailable (e.g. in CI), the `GENE_TEST` environment variable can be set to initialize the connected database instance with miniature versions of input data files before tests are executed: ::
+
+    export GENE_TEST=true
+
+.. warning::
+
+    Tests executed under the GENE_TEST environment will overwrite existing data. It is recommend that a database instance separate from the main working environment is used.
+
+
+Documentation
+-------------
+
+The documentation is built with Sphinx, which is included as part of the developer dependencies. To build a local copy, navigate to the `docs/` subdirectory and use `make` to build the HTML version: ::
+
+    cd docs
+    make html
+
+See the `Sphinx documentation <https://www.sphinx-doc.org/en/master/>`_ for more information.

docs/source/full_install.rst

@@ -0,0 +1,69 @@
+.. _full_install:
+
+Full Installation
+=================
+
+Requirements
+------------
+
+* A UNIX-like environment (e.g. MacOS, WSL, Ubuntu) with superuser permissions
+* Python 3.8+
+* A recent version of PostgreSQL (ideally at least 11+), if using PostgreSQL as the database backend
+* An available Java runtime (version 8.x or newer), or Docker Desktop, if using DynamoDB as the database backend
+
+Package installation
+--------------------
+
+First, install the Gene Normalizer from PyPI: ::
+
+    pip install gene-normalizer[dev]
+
+The ``[dev]`` option installs dependencies necessary for using the ``gene.etl`` package, which performs data loading operations.
+
+
+SeqRepo
+-------
+
+Next, acquire `SeqRepo <https://github.com/biocommons/biocommons.seqrepo>`_ sequence and alias data. ::
+
+    sudo mkdir /usr/local/share/seqrepo
+    sudo chown $USER /usr/local/share/seqrepo
+    seqrepo pull -i 2021-01-29  # Replace with latest version using `seqrepo list-remote-instances` if outdated
+
+If you encounter an error like the following: ::
+
+    PermissionError: [Error 13] Permission denied: '/usr/local/share/seqrepo/2021-01-29._fkuefgd' -> '/usr/local/share/seqrepo/2021-01-29'
+
+You may need to manually finish moving sequence files (replace the `XXXXXX` characters in the path below with the temporary name created by your instance): ::
+
+    sudo mv /usr/local/share/seqrepo/2021-01-29.XXXXXXX /usr/local/share/seqrepo/2021-01-29
+
+
+Database setup
+--------------
+
+The Gene Normalizer requires a separate database process for data storage and retrieval. See the instructions on database setup and initialization for the available database options:
+
+* :ref:`dynamodb`
+* :ref:`postgres`
+
+
+Loading data
+------------
+
+To load all source data, and then generate normalized records, use the following shell command: ::
+
+    gene_norm_update --update_all --update_merged
+
+This will download the latest available versions of all source data files, extract and transform recognized gene concepts, load them into the database, and construct normalized concept groups. For more specific update commands, see the TODO SECTION ON THAT REF OUT
+
+.. _starting-service:
+
+Starting service
+----------------
+
+Start an instance of the gene normalizer API: ::
+
+    uvicorn gene.main:app --port=5000
+
+Point your browser to http://localhost:5000/gene/. You should see the SwaggerUI page demonstrating available REST endpoints.