Merge ReST and Sphinx doc

README.rst

@@ -2,16 +2,7 @@
 AO Workflow on Docker
 =====================
 
-The principal components of this project are:
+The documentation is hosted on `AO Workflow Github Pages<https://buda-base.github.io/ao-workflows/>`_
 
-#. Docker
-#. Airflow
-#. The dags that implement airflow workflows
-
-Setting up Message Queues
-=========================
-
-See AWSIntake/setup-aws.py. You can extend it to other buckets and message names
-Run from an authorized AWS account.
 
 

doc/source/Install.rst

@@ -13,6 +13,7 @@ so it must contain all the DAG's dependencies (except airflow itself)
 
 Definitions
 -----------
+
 :host: The physical machine that the docker containers run on  (real world). in a docker compose ``volumes`` stanza, this is the left hand side of the colon. In a ``secrets:`` stanza, it's the terminal node.
 
 :container: The docker container that is running.

doc/source/Making.rst

@@ -0,0 +1,100 @@
+Making this doc
+===============
+
+Learning ReST, Sphinx, and the GitHub page system required many visits to Github Copilot, as Rest+Sphinx is not a native fit on Github yet.
+
+These sites were useful starting points and guideposts:
+
+
+
+Get Sphinx
+----------
+
+`Get Sphinx <https://www.sphinx-doc.org/en/master/tutorial/getting-started.html>`_
+
+
+Configure AO Workflows repo for GitHubPages
+-------------------------------------------
+
+Go to the `AO Workflows | Settings | Pages <https://github.com/buda-base/ao-workflows/settings/pages>`_ (you can find this in the repo's settings left nav bar as shown)
+
+
+.. image:: /.images/GitHubPagesSettings.png
+
+
+and set the
+*branch* to ``gh-pages`` and the ``source`` to ``docs/``, as shown above.
+
+This creates a Github action that will build the pages when the `gh-branch` is pushed to. See
+
+Then, simply fetch the ``gh-pages`` branch, and work in it.
+
+.. tip::
+
+    Before beginning work, update the `gh-pages` branch from main. If future developers enable the code documentation, this will help keep the documentation up to date.
+
+.. code-block:: bash
+
+    # Open this project
+    cd docs
+    git checkout gh-pages
+
+Build
+-----
+
+.. code-block:: bash
+
+    git pull origin gh-pages
+    # Bring in any doc changes
+    git merge main gh-pages
+    # Make the docs
+    ./make.sh
+
+Other targets
+-------------
+There are other useful dedicated targets for ``make.sh``
+
+:build: The default, builds the html, and runs the ``Makefile`` target ``copy-files`` which places the build output where Github pages can find it: in the ``docs/`` directory.
+
+:clean: Removes the build directory
+
+:clean_build: the ``build`` target copies a lot of stuff into the ``docs/`` directory. This removes it. Not necessary, but sometimes helpful.
+
+Review
+------
+
+.. code-block:: bash
+
+   # open the generated html in your browser
+   open build/html/index.html
+
+Commit
+------
+
+.. code-block:: bash
+
+    git commit
+    git push [origin] [gh-pages]
+
+
+Review Github progress
+----------------------
+
+In the **Actions** tab, of the `AO Workflows` repo, you can you can monitor the progress of the build. See :ref:_build-progress for more information.
+
+If the run succeeds, the pages build and deployment link,
+
+.. image:: /.images/pages-build-and-deployment.png
+
+will take you to a results page:
+
+.. image:: /.images/deployment.png
+
+which has a `link to the deployed pages <https://buda-base.github.io/ao-workflows>`_ that you can link to.
+
+.
+
+
+
+
+

doc/source/conf.py

@@ -0,0 +1,33 @@
+# 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 = 'AO Workflows'
+copyright = '2024, Buddhist Digital Resource Center'
+author = 'Buddhist Digital Resource Center'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+#
+# Don't need .nojekyll if you use these exts
+# https://olgarithms.github.io/sphinx-tutorial/docs/7-hosting-on-github-pages.html
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.githubpages",
+]
+
+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 = 'classic'
+html_static_path = ['_static']

doc/source/index.rst

@@ -12,6 +12,7 @@ Welcome to BDRC Airflow's documentation!
 
    Install
    Development
+   Making
 
 Indices and tables
 ==================
@@ -20,16 +21,3 @@ Indices and tables
   :ref:`modindex`
   :ref:`search`
 
-Making this doc
-===============
-
-.. code-block:: bash
-
-   # Open this project
-   cd doc
-   git checkout gh-pages
-   make SOURCEDIR=source BUILDDIR=build clean html
-
-   # open the generated html in your browser
-   open build/html/index.html
-   git push [origin] [gh-pages]

docs/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 1388f196d5df1d3aa11ff71ddf0ab53b
+tags: 645f666f9bcd5a90fca523b33c5a78b7