Initial docs publication

ihmeuw · Dec 16, 2024 · b1179b6 · b1179b6
1 parent cedc900
commit b1179b6
Show file tree

Hide file tree

Showing 14 changed files with 101 additions and 10 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -40,3 +40,8 @@ jobs:
       - name: Test
         run: |
           pytest ./tests
+      - name: Build Docs
+        run: |
+          pip install -r docs/requirements.txt
+          make html -C docs/ SPHINXOPTS="-W --keep-going -n"
+          
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,3 +1,7 @@
+**0.1.2 - 12/16/24**
+
+ - Initial documentation publication
+
 **0.1.1 - 12/10/24**
 
  - Implement pipeline choice sections

diff --git a/Jenkinsfile b/Jenkinsfile
@@ -148,7 +148,7 @@ pipeline {
       }
     }
 
-    stage("Test") {
+    stage("Test and Build Docs") {
       parallel {
         stage("Run End-to-End Tests") {
           steps {
@@ -194,6 +194,12 @@ pipeline {
             ])
           }
         }
+
+        stage("Build Docs") {
+          steps {
+            sh "${ACTIVATE} && make build-doc"
+          }
+        }
       }
     }
   }

diff --git a/docs/nitpick-exceptions b/docs/nitpick-exceptions
diff --git a/docs/source/api_reference/cli.rst b/docs/source/api_reference/cli.rst
@@ -0,0 +1 @@
+.. automodule:: easylink.cli
diff --git a/docs/source/api_reference/index.rst b/docs/source/api_reference/index.rst
@@ -0,0 +1,10 @@
+API Reference
+=============
+
+.. automodule:: easylink
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *
diff --git a/docs/source/concepts/index.rst b/docs/source/concepts/index.rst
@@ -0,0 +1,10 @@
+.. _concepts_main:
+
+========
+Concepts
+========
+Here we cover several core conceptual topics related using EasyLink.
+
+.. todo::
+
+   Everything
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -59,8 +59,6 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_click.ext",
-    "matplotlib.sphinxext.plot_directive",
-    "sphinxcontrib.video",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -2,4 +2,18 @@
 EasyLink Documentation
 ======================
 
-EasyLink is a framework for ... tbd
+EasyLink is a framework for ...
+
+.. todo::
+
+   Everything
+
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   tutorials/index
+   concepts/index
+   api_reference/index
+   glossary
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -1,3 +1,5 @@
+.. _installation:
+
 ===================
 Installing EasyLink
 ===================
@@ -9,5 +11,6 @@ Installing EasyLink
 
 .. highlight:: console
 
-tbd
+.. todo::
 
+   Everything
diff --git a/docs/source/tutorials/getting_started.rst b/docs/source/tutorials/getting_started.rst
@@ -0,0 +1,9 @@
+.. _getting_started_tutorial:
+
+===============
+Getting Started
+===============
+
+.. todo::
+
+   Everything
diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst
@@ -0,0 +1,21 @@
+.. _tutorial_main:
+
+=========
+Tutorials
+=========
+Here you'll find a set of tutorials to introduce concepts and functionality
+available in the ``easylink`` package.
+
+Before digging into the tutorials, please walk through the
+:doc:`getting started <getting_started>` guide.
+
+.. todo::
+
+   Everything
+
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *
diff --git a/setup.py b/setup.py
@@ -33,12 +33,22 @@
     setup_requires = ["setuptools_scm"]
 
     # use "pip install -e .[dev]" to install required components + extra components
-    data_requires = []
     test_requirements = [
         "pytest",
         "pytest-cov",
         "pytest-mock",
     ]
+    doc_requirements = [
+        "sphinx>=4.0,<8.0.0",
+        "sphinx-rtd-theme>=0.6",
+        "sphinx-autodoc-typehints",
+        "sphinx-click",
+    ]
+    lint_requirements = [
+        "black==22.3.0",
+        "isort",
+        "mypy",
+    ]
 
     setup(
         name=about["__title__"],
@@ -53,9 +63,9 @@
         include_package_data=True,
         install_requires=install_requirements,
         extras_require={
+            "docs": doc_requirements,
             "test": test_requirements,
-            "data": data_requires,
-            "dev": test_requirements + data_requires,
+            "dev": doc_requirements + test_requirements + lint_requirements,
         },
         zip_safe=False,
         use_scm_version={

diff --git a/src/easylink/__init__.py b/src/easylink/__init__.py
@@ -1,7 +1,7 @@
 """
-======
+========
 EasyLink
-======
+========
 
 Research repository for the EasyLink ER ecosystem project.