Setup our docs and host to github pages [CU-868byp419]

.github/workflows/docs_build.yml

@@ -0,0 +1,36 @@
+name: docs (build)
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - .pre-commit-config.yaml
+      - .github/workflows/docs_build.yml
+      - '**.py'
+      - '**.ipynb'
+      - '**.js'
+      - '**.html'
+      - poetry.lock
+      - pyproject.toml
+      - '**.rst'
+      - '**.md'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected]
+      - name: Install dependencies and build docs
+        run: python3 -m pip install --upgrade pip && python3 -m pip install poetry
+      - uses: actions/[email protected]
+        with:
+          python-version: '3.10'
+          cache: 'poetry'
+      - run: |
+          python3 -m pip install --upgrade pip && python3 -m pip install poetry
+          poetry env use '3.10'
+          source $(poetry env info --path)/bin/activate
+          poetry install --with docs,test
+          cd docs && rm -rf source/reference/api/_autosummary && make html

.github/workflows/docs_publish.yml

@@ -0,0 +1,47 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - .pre-commit-config.yaml
+      - .github/workflows/code_checks.yml
+      - .github/workflows/docs_build.yml
+      - .github/workflows/docs_deploy.yml
+      - .github/workflows/integration_tests.yml
+      - '**.py'
+      - '**.ipynb'
+      - '**.html'
+      - '**.js'
+      - poetry.lock
+      - pyproject.toml
+      - '**.rst'
+      - '**.md'
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected]
+        with:
+          submodules: 'true'
+      - name: Install dependencies and build docs
+        run: python3 -m pip install --upgrade pip && python3 -m pip install poetry
+      - uses: actions/[email protected]
+        with:
+          python-version: '3.10'
+          cache: 'poetry'
+      - name: Build Docs
+        run: |
+          python3 -m pip install --upgrade pip && python3 -m pip install poetry
+          poetry env use '3.10'
+          source $(poetry env info --path)/bin/activate
+          poetry install --with docs,test
+          cd docs && rm -rf source/reference/api/_autosummary && make html
+      - name: Deploy to Github pages
+        uses: JamesIves/[email protected]
+        with:
+          branch: github_pages
+          folder: docs/build/html

docs/Makefile

@@ -0,0 +1,24 @@
+# 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)
+
+# NOTE: This is not generated from `sphinx-quickstart` and manually added
+serve:
+	sphinx-autobuild $(SOURCEDIR) $(BUILDDIR)

docs/README.md

@@ -0,0 +1,31 @@
+# Documentation
+
+This section of the repository contains source artifacts for building the docs
+for `fl4health`.
+
+What follow's next in this README is a guide for those who are interested in
+building and serving the docs locally. You may be interested to do so if you are
+contributing to `fl4health` and need to make appropriate changes to the
+documentation.
+
+## Build Docs
+
+In order to build the docs, go into the `docs` directory and run the command
+below:
+
+```sh
+cd docs/
+make serve
+```
+
+The above command will build the docs as well as serve them locally, watching
+for changes and presenting them in real-time, which is great for development!
+
+Building the docs will take a couple of minutes, but once completed they will be
+served on `http://127.0.0.1:8000`. Enter this address in your browser of choice
+to see the docs.
+
+> [!NOTE]
+> We use sphinx to build our docs and api reference. Adjustments to style and
+> and additional extensions are done via the appropriate modifications in
+> `docs/source/conf.py`.

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/_static/custom.js

@@ -0,0 +1,6 @@
+requirejs.config({
+    paths: {
+      base: '/static/base',
+      plotly: 'https://cdn.plot.ly/plotly-2.30.0.min.js?noext',
+    },
+  });

docs/source/_templates/base.html

@@ -0,0 +1,120 @@
+<!doctype html>
+<html class="no-js"{% if language is not none %} lang="{{ language }}"{% endif %}>
+  <head>
+    {%- block site_meta -%}
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width,initial-scale=1"/>
+    <meta name="color-scheme" content="light dark">
+    <meta name="google-site-verification" content="i0qQRaR9OA3tSz_9tDocdcXGY27Ox_cy4FrvTHD2C_0" />
+
+    {%- if metatags %}{{ metatags }}{% endif -%}
+
+    {# Make sure all pages have a description or Bing does not like us #}
+    {% if 'name="description"' not in metatags %}
+      <meta name="description" content="aieng-template Python API documentation">
+    {% endif %}
+
+    {%- block linktags %}
+        {%- if hasdoc('about') -%}
+          <link rel="author" title="{{ _('About these documents') }}" href="{{ pathto('about') }}" />
+        {%- endif -%}
+        {%- if hasdoc('genindex') -%}
+          <link rel="index" title="{{ _('Index') }}" href="{{ pathto('genindex') }}" />
+        {%- endif -%}
+        {%- if hasdoc('search') -%}
+          <link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}" />
+        {%- endif -%}
+        {%- if hasdoc('copyright') -%}
+          <link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}" />
+        {%- endif -%}
+        {%- if next -%}
+          <link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}" />
+        {%- endif -%}
+        {%- if prev -%}
+          <link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}" />
+        {%- endif -%}
+        {#- rel="canonical" (set by html_baseurl) -#}
+        {%- if pageurl %}
+        <link rel="canonical" href="{{ pageurl|e }}" />
+        {%- endif %}
+    {%- endblock linktags %}
+
+    {# Favicon #}
+    {%- if favicon_url -%}
+      <link rel="shortcut icon" href="{{ favicon_url }}"/>
+    {%- endif -%}
+
+    {#- Generator banner -#}
+    <meta name="generator" content="sphinx-{{ sphinx_version }}, furo {{ furo_version }}"/>
+
+    {# Bing webmasters meta tag #}
+    <meta name="msvalidate.01" content="8D2A5032F006424CAF54C0DDCD16F666" />
+
+    {%- endblock site_meta -%}
+
+    {#- Site title -#}
+    {%- block htmltitle -%}
+      {# See Sphinx monkey patch in conf.py #}
+      {% if 'title' in metas %}
+        <title>{{ metas.title }}</title>
+      {% elif not docstitle %}
+        <title>{{ title|striptags|e }}</title>
+      {% elif pagename == master_doc %}
+        <title>{{ docstitle|striptags|e }}</title>
+      {% else %}
+        <title>{{ title|striptags|e }} - {{ docstitle|striptags|e }}</title>
+      {% endif %}
+    {%- endblock -%}
+
+    {%- block styles -%}
+
+    {# Custom stylesheets #}
+    {%- block regular_styles -%}
+    {%- for css in css_files -%}
+      {% if css|attr("filename") -%}
+        {{ css_tag(css) }}
+      {%- else -%}
+        <link rel="stylesheet" href="{{ pathto(css, 1)|e }}" type="text/css" />
+      {%- endif %}
+    {% endfor -%}
+    {%- endblock regular_styles -%}
+
+    {#- Theme-related stylesheets -#}
+    {%- block theme_styles %}
+    {% include "partials/_head_css_variables.html" with context %}
+    {%- endblock -%}
+
+    {%- block extra_styles %}
+    {%- endblock -%}
+
+    {%- endblock styles -%}
+
+    {#- Custom front matter #}
+    {%- block extrahead -%}{%- endblock -%}
+
+    {# Custom JS #}
+    {%- block regular_scripts -%}
+    {% for path in script_files -%}
+      {{ js_tag(path) }}
+    {% endfor -%}
+    {%- endblock regular_scripts -%}
+
+    {# Theme-related JavaScript code #}
+    {%- block theme_scripts -%}
+    {%- endblock -%}
+
+    {# Footer icons #}
+    <script src="https://kit.fontawesome.com/2c1f516901.js" crossorigin="anonymous"></script>
+
+  </head>
+  <body>
+    {% block body %}
+    <script>
+      document.body.dataset.theme = localStorage.getItem("theme") || "auto";
+    </script>
+    {% endblock %}
+
+    {%- block scripts -%}
+    {%- endblock scripts -%}
+  </body>
+</html>

docs/source/_templates/custom-class-template.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}