Initial commit documentation builder

Author: dwest77a

.github/workflows/sphinx_build.yml

@@ -0,0 +1,57 @@
+name: Sphinx build
+
+on:
+  # Push/Pull for main branch.
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+  # Run workflow manually from actions tab.
+  workflow_dispatch:
+    
+jobs:
+  build:
+    # Specify an OS for the runner
+    runs-on: ubuntu-latest
+
+    #Define steps
+    steps:
+
+      # Firstly, checkout repo
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      # Set up Python env
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+      # Install dependencies
+      - name: Install Python dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          pip3 install poetry
+          poetry install
+
+      - name: Build documentation
+        run: |
+          mkdir gh-pages
+          touch gh-pages/.nojekyll
+          pushd docs/source/
+          poetry run sphinx-build -b html . _build
+          popd
+          cp -r docs/source/_build/* gh-pages/
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-docs
+          path: gh-pages
+      # Deploys to the gh-pages branch if the commit was made to main, the 
+      # gh-pages then takes over serving the html
+      - name: Deploy documentation
+        if: ${{ github.event_name == 'push' }}
+        uses: JamesIves/github-pages-deploy-action@4.1.4
+        with:
+          branch: gh-pages
+          folder: gh-pages

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     = .
+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/_source/index.rst

@@ -0,0 +1,15 @@
+.. ceda-datapoint documentation master file, created by
+   sphinx-quickstart on Tue Oct 15 15:34:57 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+CCI STAC Tools
+==============
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

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/migrate_notebook.sh

@@ -0,0 +1,11 @@
+echo 1. Converting
+jupyter nbconvert --to rst ../demo/basic_usage.ipynb 
+
+echo 2. Relocating
+mv ../demo/basic_usage.rst usage.rst
+
+echo 3. Reformatting
+python rst_format.py usage.rst
+
+echo 4. Installing
+mv usage.rst source/usage.rst

docs/rst_format.py

@@ -0,0 +1,74 @@
+"""
+Turn:
+
+.. code:: ipython3
+
+    do some python
+
+.. code:: literal
+
+    result
+
+Into:
+
+.. parsed-literal:: 
+
+    >>> do some python
+    result
+"""
+
+import sys
+
+
+def reformat_file(filename: str, ofile: str = None):
+    """
+    Reformat a generated file to use as documentation with testing
+    """
+
+    with open(filename) as f:
+        lines = [r.replace('\n','') for r in f.readlines()]
+
+    rst = []
+    in_code_block = False
+    python = False
+    literal = False
+    for x, l in enumerate(lines):
+
+        if not bool(l):
+            if not in_code_block:
+                rst.append(l)
+            continue
+        elif '.. code::' in l or '.. parsed-literal::' in l:
+            if not in_code_block or literal:
+                if literal:
+                    rst.append('')
+                l = '.. code::'
+                in_code_block = True
+                python = True
+                literal = False
+                rst.append(l)
+                rst.append('')
+            else:
+                literal = True
+                python = False
+        elif not l.startswith(' '):
+            if in_code_block:
+                in_code_block = False
+                rst.append('')
+            rst.append(l)
+        else:
+            if python:
+                rst.append(f'   >>> {l[4:]}')
+            else:
+                rst.append(l[1:])
+
+    if ofile is None:
+        ofile = filename
+
+    with open(ofile, 'w') as f:
+        f.write('\n'.join(rst))
+
+    print(f'Written to output file: {ofile}')
+
+if __name__ == '__main__':
+    reformat_file(sys.argv[-1])