configure documentation

astro-datalab · Dec 12, 2024 · d6e2745 · d6e2745
1 parent e6310cb
commit d6e2745
Show file tree

Hide file tree

Showing 5 changed files with 107 additions and 28 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -72,28 +72,28 @@ jobs:
     #             COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
     #           run: coveralls
 
-    # docs:
-    #     name: Doc test
-    #     runs-on: ${{ matrix.os }}
-    #     strategy:
-    #         fail-fast: false
-    #         matrix:
-    #             os: [ubuntu-latest]
-    #             python-version: ['3.9']
+    docs:
+        name: Doc test
+        runs-on: ${{ matrix.os }}
+        strategy:
+            fail-fast: false
+            matrix:
+                os: [ubuntu-latest]
+                python-version: ['3.9']
 
-    #     steps:
-    #         - name: Checkout code
-    #           uses: actions/checkout@v4
-    #           with:
-    #             fetch-depth: 0
-    #         - name: Set up Python ${{ matrix.python-version }}
-    #           uses: actions/setup-python@v5
-    #           with:
-    #             python-version: ${{ matrix.python-version }}
-    #         - name: Install Python dependencies
-    #           run: python -m pip install --upgrade pip setuptools wheel Sphinx
-    #         - name: Test the documentation
-    #           run: sphinx-build -W --keep-going -b html docs docs/_build/html
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+              with:
+                fetch-depth: 0
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python-version }}
+            - name: Install Python dependencies
+              run: python -m pip install --upgrade pip setuptools wheel Sphinx
+            - name: Test the documentation
+              run: sphinx-build -W --keep-going -b html docs docs/_build/html
 
     style:
         name: Style check

diff --git a/dlairflow/postgresql.py b/dlairflow/postgresql.py
@@ -27,7 +27,7 @@ def pg_dump_schema(connection, schema, dump_dir=None):
 
     Returns
     -------
-    BashOperator
+    :class:`~airflow.operators.bash.BashOperator`
         A BashOperator that will execute :command:`pg_dump`.
     """
     if dump_dir is None:
@@ -60,7 +60,7 @@ def pg_restore_schema(connection, schema, dump_dir=None):
 
     Returns
     -------
-    BashOperator
+    :class:`~airflow.operators.bash.BashOperator`
         A BashOperator that will execute :command:`pg_dump`.
     """
     if dump_dir is None:

diff --git a/docs/api.rst b/docs/api.rst
@@ -5,11 +5,8 @@ dlairflow API
 .. automodule:: dlairflow
     :members:
 
-.. automodule:: dlairflow.base
+.. automodule:: dlairflow.postgresql
     :members:
 
-.. automodule:: dlairflow.sdss
-    :members:
-
-.. automodule:: dlairflow.view
+.. automodule:: dlairflow.util
     :members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,63 @@
+# 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
+
+import os
+import sys
+from importlib import import_module
+sys.path.insert(0, os.path.abspath('..'))
+
+
+project = 'dlairflow'
+copyright = '2024, Astro Data Lab'
+author = 'Astro Data Lab'
+package = import_module(project)
+version = '.'.join(package.__version__.split('.')[:2])
+release = package.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.todo',
+    'sphinx.ext.githubpages',
+    'sphinx_rtd_theme'
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# We don't necessarily need a full installation to build documentation.
+autodoc_mock_imports = []
+for missing in ('airflow', ):
+    try:
+        foo = import_module(missing)
+    except ImportError:
+        autodoc_mock_imports.append(missing)
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+# html_static_path = ['_static']
+
+# -- Options for intersphinx extension ---------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'airflow': ('https://airflow.apache.org/docs/apache-airflow/stable/', None)
+}
+
+# -- Options for todo extension ----------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration
+
+todo_include_todos = True
diff --git a/docs/index.rst b/docs/index.rst
@@ -0,0 +1,19 @@
+.. dlairflow documentation master file, created by
+   sphinx-quickstart on Thu Dec 12 16:04:44 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+dlairflow documentation
+=======================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   api.rst
+   changes.rst