Merge branch 'dev' into gtfs-html-new

.github/workflows/sphinx-render.yml

@@ -0,0 +1,34 @@
+name: "Render docs"
+
+on: push
+
+env:
+  PYTHON_VERSION: "3.9"
+  PUSH_BRANCH: "refs/heads/dev"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ env.PYTHON_VERSION }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Sphinx build  # use -W to turn warnings into errors
+      run: |
+        make -C docs/ html SPHINXOPTS="-W"
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      # deploy if it's being pushed only to this branch
+      if: ${{ github.ref ==  env.PUSH_BRANCH }}
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html
+        commit_message: ${{ github.event.head_commit.message }}

.gitignore

@@ -174,7 +174,12 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/source/reference/_autosummary/
+docs/build/
+!docs/README.md
+!docs/gtfs
+!docs/source/_static/dsc.png
+!docs/source/_templates/footer.html
 
 # PyBuilder
 .pybuilder/
@@ -313,11 +318,6 @@ vignettes/*.pdf
 # R Environment Variables
 .Renviron
 
-# pkgdown site
-docs/*
-!docs/README.md
-!docs/gtfs
-
 # translation temp files
 po/*~
 

README.md

@@ -1,5 +1,5 @@
 <!--- Badges start --->
-<img src="https://img.shields.io/badge/repo%20status-in%20development%20(caution)-red" alt="Repository status is still in development (caution required)"/> <img src="https://github.com/datasciencecampus/transport-network-performance/actions/workflows/python-package.yml/badge.svg" alt="Build status badge"/> <a href="https://codecov.io/gh/datasciencecampus/transport-network-performance" > <img src="https://codecov.io/gh/datasciencecampus/transport-network-performance/branch/dev/graph/badge.svg?token=ZKJFT321CN"/></a>
+<img src="https://img.shields.io/badge/repo%20status-in%20development%20(caution)-red" alt="Repository status is still in development (caution required)"/> <img src="https://github.com/datasciencecampus/transport-network-performance/actions/workflows/python-package.yml/badge.svg" alt="Build status badge"/> <img src="https://github.com/datasciencecampus/transport-network-performance/actions/workflows/sphinx-render.yml/badge.svg" alt="Docs status badge"/> <a href="https://codecov.io/gh/datasciencecampus/transport-network-performance" > <img src="https://codecov.io/gh/datasciencecampus/transport-network-performance/branch/dev/graph/badge.svg?token=ZKJFT321CN"/></a>
 
 <!--- Badges end --->
 

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     = 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)

docs/README.md

@@ -1,3 +1,88 @@
 # `docs` folder overview
 
-All documentation for the project should be included in this folder.
+This folder contains all the source files needed to build package documentation
+using [`sphinx`](https://www.sphinx-doc.org/en/master/).
+
+## Building the documentation locally
+
+This is useful whilst editing the documentation locally and previewing new
+additions/edits. Following the steps below will render the documenation locally
+allowing you to check for any warnings or errors during the build stage.
+
+1. Ensure the dependencies in `requirements.txt` have been installed. This will
+install `sphinx`, the necessary themes, and all the other Python dependecies
+for this package.
+
+2. Call the following from the project root:
+
+    ```bash
+    make -C docs/ html
+    ```
+
+    Or, from the within this docs directory:
+
+    ```bash
+    make html
+    ```
+
+    > Note: On Windows, if you are using PowerShell the make command may not
+    work. If this is the case, you should be able to run `.\make.bat html`
+    after navigating to this directory.
+
+    Calling one of the commands above will trigger `sphinx-build` and render
+    the documentaion in HTML format within the `build` directory.
+
+3. Inside `docs/build/html/`, opening/refreshing `index.html` in a browser will
+display the documentation landing page.
+
+## Cleaning the docs folder
+
+From time to time, it maybe necessary to clean the build folder (e.g., to
+unpick some edits that have not made their way through to the browser for some
+reason).
+
+> Note: `sphinx-build` will only rebuild pages if the respective source file(s)
+has changed. Calling clean maybe helpful to either force an entire rebuild of
+all pages, or include an update that isn't picked up via a source (e.g. a CSS
+file update).
+
+To clean the build folder, call the following:
+
+```bash
+# from the project root
+make -C docs/ clean
+
+# or, from within the docs folder
+make clean
+```
+
+It's also possible to combine both the clean and HTML build commands together
+as follows:
+
+```bash
+# from the project root
+make -C docs/ clean html
+
+# or, from within the docs folder
+make clean html
+```
+
+> Note: the contents of the `docs/build` folder are ignored by Git. Cleaning
+the build folder locally will therefore only impact your local documentation
+build.
+
+## Building the documentation 'on push' to a remote branch
+
+There is a GitHub action set-up (`.github/workflows/sphinx-render.yml`) that
+runs on all pushes to any branch. This will attempt to build the `docs/source`
+folder content and will fail if `sphinx-build` throws any errors or warnings.
+This helps ensure the quality of the documentation on each push and allows
+developers to correct any issues sooner.
+
+The deployment stage of this GitHub action is only done when pushing to the
+`dev` branch (i.e. after merging in a PR). Therefore, any changes made to
+`docs` in a feature branch will not appear in the deployed documentation.
+
+> Note: the current implementation of the GitHub action deploys on push to
+`dev` but this is subject to change at a later date. It will likely be change
+to puses to `main` once an inital release of this package is available.

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.css

@@ -0,0 +1,6 @@
+/* Provision for custom css */
+
+/* wraps text in toctree to fit into sidebar width */
+li[class^="toctree"] {
+    word-break: break-all;
+}

docs/source/_templates/autosummary/base.rst

@@ -0,0 +1,8 @@
+..
+  base.rst
+
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,23 @@
+..
+  class.rst
+
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+    :members:
+    :show-inheritance:
+    :inherited-members:
+
+    {% block methods %}
+        {% if methods %}
+            .. rubric:: {{ _('Methods') }}
+
+            .. autosummary::
+                :nosignatures:
+                {% for item in methods %}
+                    ~{{ name }}.{{ item }}
+                {%- endfor %}
+        {% endif %}
+    {% endblock %}

docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,74 @@
+..
+  module.rst
+
+{{ fullname | escape | underline }}
+
+.. automodule:: {{ fullname }}
+
+    {% block attributes %}
+        {% if attributes %}
+            .. rubric:: Module Attributes
+
+            .. autosummary::
+                :toctree:
+                {% for item in attributes %}
+                    {{ item }}
+                {%- endfor %}
+        {% endif %}
+    {% endblock %}
+
+    {% block functions %}
+        {% if functions %}
+            .. rubric:: {{ _('Functions') }}
+
+            .. autosummary::
+                :toctree:
+                :nosignatures:
+                :template: autosummary/base.rst
+                {% for item in functions %}
+                    {{ item }}
+                {%- endfor %}
+        {% endif %}
+    {% endblock %}
+
+    {% block classes %}
+        {% if classes %}
+            .. rubric:: {{ _('Classes') }}
+
+            .. autosummary::
+                :toctree:
+                :nosignatures:
+                :template: autosummary/class.rst
+                {% for item in classes %}
+                    {{ item }}
+                {%- endfor %}
+        {% endif %}
+    {% endblock %}
+
+    {% block exceptions %}
+        {% if exceptions %}
+            .. rubric:: {{ _('Exceptions') }}
+
+            .. autosummary::
+                :toctree:
+                :nosignatures:
+                :template: autosummary/base.rst
+                {% for item in exceptions %}
+                    {{ item }}
+                {%- endfor %}
+        {% endif %}
+    {% endblock %}
+
+{% block modules %}
+    {% if modules %}
+        .. rubric:: Modules
+
+        .. autosummary::
+            :toctree:
+            :template: autosummary/module.rst
+            :recursive:
+            {% for item in modules %}
+                {{ item }}
+            {%- endfor %}
+    {% endif %}
+{% endblock %}

docs/source/_templates/footer.html

@@ -0,0 +1,27 @@
+{% extends "!footer.html" %}
+
+{%- block extrafooter %}
+
+    <br><br>
+
+    <div>
+        Checkout the
+        <a href="https://github.com/datasciencecampus/transport-network-performance">
+            codebase on GitHub.
+        </a>
+    </div>
+
+    <br>
+
+    <div>
+        For more ONS Data Science Campus news see the
+        <a href="https://datasciencecampus.ons.gov.uk/">
+            Campus' website
+        </a>
+        and
+        <a href="https://twitter.com/i/flow/login?redirect_after_login=%2FDataSciCampus">
+            follow us on Twitter.
+        </a>
+    </div>
+
+{% endblock %}