First draft of documentation (#259)

* First draft of documentation * More detail on tutorial * Format tutorial codeblock * chore: ignored additional quarto docs files * chore: removed GTFS class instance diagram * chore: added consistent preview port * chore: added favicon * chore: styled nav and footer using GAF colour palette * chore: updated layout of about page * chore: added placeholder getting started page * chore: refactored explanations directory * chore: added explanation placeholders * chore: restructured tutorials sidebar hierarchy * chore: reduced size of footer image * chore: added how-to placeholders * chore: updated where do I go now * chore: added diataxis to footer * chore: typos in where do I go now; added contribution section * chore: added tutorials placeholders * chore: added urban centres init for quartodoc * docs: removed method section for quartodoc * docs: added urban centres API * docs: removed method section for quartodoc * docs: added population API * docs: removed methods section for quartodoc * docs: removed methods and warns for quartodoc; added spaces by colons in docstrings * docs: added gtfs API * chore: added osm init for quartodoc * docs: added osm_utils API * docs: removed methods section for quartodoc * docs: added analyse_network API * docs: added metrics API * docs: removed reference section for quartodoc * docs: added utils API * chore: removed sphinx docs * chore: refactored getting started to dir * chore: renamed docs workflow; added java, geospatial, and quarto render steps; removed sphinx steps * chore: updated docs README with quarto instructions * refactor: Minor typo & language * refactor: All sub-indexes use tables with ui sort on numbered items * fix: Typo in yaml * fix: Typos & table render in docstrings * fix: Small typo in rasterpop docstring * fix: Rm curly braces in docstring * docs: Add update to deprecation warning * fix: Typos & clearer explanations in gtfs.multi_validation docstrings * fix: Typo in gtfs.routes docstrings * fix: Minor language opinions in gtfs.validation docstrings * fix: Minor docstring typos in analyse_network * docs: Mention alternative backends not implemented * fix: Minor docstring typo in raster util --------- Co-authored-by: Ethan Moss <[email protected]> Co-authored-by: r-leyshon <[email protected]>
datasciencecampus · May 22, 2024 · 0d8e0da · 0d8e0da
1 parent cbdf383
commit 0d8e0da
Show file tree

Hide file tree

Showing 53 changed files with 522 additions and 641 deletions.
diff --git a/.github/workflows/sphinx-render.yml → .github/workflows/quarto-render.yml b/.github/workflows/sphinx-render.yml → .github/workflows/quarto-render.yml
@@ -3,15 +3,16 @@
 
 name: "Render docs"
 
-on: push
+on:
+  push:
+    branches: [ "dev", "main" ]
 
 env:
   PYTHON_VERSION: "3.9"
-  PUSH_BRANCH: "refs/heads/dev"
 
 jobs:
   build:
-    name: Sphinx
+    name: Quarto Render
     runs-on: ubuntu-22.04
     permissions:
       contents: write
@@ -25,14 +26,24 @@ jobs:
       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
+    - name: Install java
+      uses: actions/setup-java@v3
+      with:
+        distribution: 'temurin'
+        java-version: '11.0.21'
+    - name: Check Java Install
+      run: |
+        java --version
+    - name: Install linux depencies with apt
       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 }}
+        sudo apt update
+        sudo apt install -y libgeos-dev
+      shell: sh
+    - name: Set up Quarto
+      uses: quarto-dev/quarto-actions/setup@v2
+    - name: Render and Publish
+      uses: quarto-dev/quarto-actions/publish@v2
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: docs/build/html
-        commit_message: ${{ github.event.head_commit.message }}
+        target: gh-pages
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -192,6 +192,9 @@ docs/build/
 !docs/gtfs
 !docs/source/_static/dsc.png
 !docs/source/_templates/footer.html
+docs/_sidebar.yml
+docs/reference/
+!docs/_static/tp_logo_white_background.png
 
 # PyBuilder
 .pybuilder/
@@ -370,3 +373,11 @@ $RECYCLE.BIN/
 .vscode/
 
 # End of https://www.toptal.com/developers/gitignore/api/macos,windows,r,python
+
+# venv
+.venv/
+
+# Quarto
+/.quarto/
+_site/
+objects.json
diff --git a/_quarto.yml b/_quarto.yml
@@ -0,0 +1,157 @@
+project:
+  type: website
+  render:
+    - "index.qmd"
+    - "docs/"
+    - "!notebooks/"
+    - "!docs/source/"
+    - "!docs/build/"
+    - "!*.ipynb"
+    - "!docs/gtfs/*"
+  preview:
+    port: 1111
+    browser: true
+    watch-inputs: true
+    navigate: true
+  resources:
+    - "docs/_static/**"
+
+website:
+  title: "Transport Performance"
+  favicon: docs/_static/favicon.ico
+  navbar:
+    logo: docs/_static/tp_logo_white_background.png
+    left:
+      - href: docs/getting_started/index.qmd
+        text: Getting Started
+      - href: docs/explanation/index.qmd
+        text: Explanation
+      - href: docs/how_to/index.qmd
+        text: How-To
+      - href: docs/tutorials/index.qmd
+        text: Tutorials
+      - href: docs/reference/index.qmd
+        text: API Reference
+    right:
+      - icon: github
+        menu:
+          - text: Source code
+            url: https://github.com/datasciencecampus/transport-network-performance
+          - text: Open an issue
+            url: https://github.com/datasciencecampus/transport-network-performance/issues
+  sidebar:
+    style: docked
+    search: true
+    collapse-level: 1
+    contents:
+      - text: Getting Started
+        href: docs/getting_started/index.qmd
+      - section: Explanation
+        href: docs/explanation/index.qmd
+        contents:
+          - "docs/explanation/what_is_tp/index.qmd"
+          - "docs/explanation/calculate_tp/index.qmd"
+          - "docs/explanation/limitations/index.qmd"
+      - section: How-To
+        href: docs/how_to/index.qmd
+        contents:
+          - auto: "docs/how_to/**/*.qmd"
+      - section: Tutorials
+        href: docs/tutorials/index.qmd
+        contents:
+          - "docs/tutorials/urban_centre/index.qmd"
+          - "docs/tutorials/population/index.qmd"
+          - "docs/tutorials/gtfs/index.qmd"
+          - "docs/tutorials/osm/index.qmd"
+          - "docs/tutorials/analyse_network/index.qmd"
+          - "docs/tutorials/metrics/index.qmd"
+      - section: API Reference
+        href: docs/reference/index.qmd
+        contents:
+          - auto: "docs/reference/*.qmd"
+  reader-mode: true
+  page-footer:
+    left: >
+      These docs are built using [Quarto](https://quarto.org/), [quartodoc](https://machow.github.io/quartodoc/get-started/overview.html), and [Diátaxis](https://diataxis.fr/).
+    center: >
+      All content is available under the
+      [Open Government Licence V3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/),
+      except where otherwise stated.
+    right: >
+      <a href="https://datasciencecampus.ons.gov.uk/">
+        <img src="https://datasciencecampus.ons.gov.uk/wp-content/uploads/sites/10/2019/05/DSC.png" alt="Data Science Campus logo" style="height:22px;">
+      </a>
+
+format:
+  html:
+    mainfont: Arial
+    theme:
+      - flatly
+      - docs/_static/custom.scss
+    lang: en-GB
+
+metadata-files:
+  - docs/_sidebar.yml
+
+quartodoc:
+  title: API reference
+  package: transport_performance
+  dir: docs/reference
+  sidebar: docs/_sidebar.yml
+  sections:
+    - title: "`urban_centres`"
+      desc: >
+        Modules for detecting urban centres.
+    - subtitle: "`urban_centres.raster_uc.UrbanCentre`"
+      desc: >
+        A class for detecting urban centres using rastered population estimates.
+      package: transport_performance.urban_centres.raster_uc
+      contents:
+        - UrbanCentre
+    - title: "`population`"
+      desc: >
+        Modules for preprocessing population data.
+    - subtitle: "`population.rasterpop.RasterPop`"
+      desc: >
+        A class for preprocessing rastered population estimates.
+      package: transport_performance.population.rasterpop
+      contents:
+        - RasterPop
+    - title: "`gtfs`"
+      desc: >
+        Modules for working with GTFS public transit schedule files.
+      package: transport_performance.gtfs
+      contents:
+        - calendar
+        - cleaners
+        - gtfs_utils
+        - multi_validation
+        - routes
+        - validation
+        - validators
+    - title: "`osm`"
+      desc: >
+        Modules for OpenStreetMap utilities, such are cropping .pbf files to a bounding box.
+      package: transport_performance.osm
+      contents:
+        - osm_utils
+    - title: "`analyse_network`"
+      desc: >
+        A class wrapping r5py network routing to calculate travel times between all origin/destination cells.
+      package: transport_performance.analyse_network
+      contents:
+        - AnalyseNetwork
+    - title: "`metrics`"
+      desc: >
+        Functions for calculating transport metrics, such as transport performance.
+      package: transport_performance
+      contents:
+        - metrics
+    - title: "`utils`"
+      desc: >
+        Modules to handle common package utility functions.
+      package: transport_performance.utils
+      contents:
+        - defence
+        - io
+        - raster
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/README.md b/docs/README.md
@@ -1,88 +1,27 @@
 # `docs` folder overview
 
-This folder contains all the source files needed to build package documentation
-using [`sphinx`](https://www.sphinx-doc.org/en/master/).
+This folder contains all the source files needed to build package documentation.
 
-## Building the documentation locally
+## Using Quarto with Quartodoc
 
-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.
+To build the documentation using Quarto and quartodoc, you will need to install [Quarto](https://quarto.org/docs/get-started/).
 
-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.
+The Python package, `quartodoc`, is included in the project 'requirements.txt'.
 
-2. Call the following from the project root:
+Run `quartodoc build` in the top-level folder; this will create a new directory, `docs/reference/` and populate it with automatically generated `.qmd` files for each reference documentation page.
 
-    ```bash
-    make -C docs/ html
-    ```
+Then run `quarto preview` to view a local rendering of the website.
 
-    Or, from the within this docs directory:
+Adding to the docs can be done as follows:
 
-    ```bash
-    make html
-    ```
+- New tutorials can be added to `docs/tutorials/`.
+- New How-to guides can be added to `docs/how_to/`.
+- New explanation guides can be added to `docs/explanation/`.
+- In all cases, create a new subdirectory in one of the above areas and then create an `index.qmd` file to add page content. All assets pertaining to the new page can then also be stored within this sub directory.
 
-    > 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.
+There is a GitHub action set-up (`.github/workflows/quarto-render.yml`) that
+runs on all pushes to the `dev` and `main` branches. This will attempt to render
+the content within `docs/` and then deploy them to the `gh-pages` branch.
diff --git a/docs/_static/custom.scss b/docs/_static/custom.scss
@@ -0,0 +1,12 @@
+/*-- scss:defaults --*/
+
+// footer config
+$footer-bg: #414042;
+$footer-fg: white;
+
+// navbar config
+$navbar-bg: #3b7a9e;
+
+// links and inline styling
+$link-color: #206095;
+$code-color: #801650;
diff --git a/docs/source/_static/favicon.ico → docs/_static/favicon.ico b/docs/source/_static/favicon.ico → docs/_static/favicon.ico
diff --git a/docs/_static/tp_logo_white_background.png b/docs/_static/tp_logo_white_background.png
diff --git a/docs/explanation/calculate_tp/index.qmd b/docs/explanation/calculate_tp/index.qmd
@@ -0,0 +1,10 @@
+---
+title: "2. Transport Performance: An Example"
+description: An overview of how we used `transport_performance` to calculate the transport performance of urban centre public transit networks.
+date-modified: 05/16/2024  # must be in MM/DD/YYYY format
+categories: ["Explanation"]  # see https://diataxis.fr/tutorials-how-to/#tutorials-how-to, delete as appropriate
+toc: true
+date-format: iso
+---
+
+🚧 Page under construction 🚧
diff --git a/docs/explanation/index.qmd b/docs/explanation/index.qmd
@@ -0,0 +1,13 @@
+---
+title: Explanation
+listing:
+    type: table
+    contents:
+        - "/**/*.qmd"
+    fields: [title, description, reading-time]
+    sort: title
+    sort-ui: true
+    filter-ui: true
+---
+
+These explanation pages provide an understanding of what Transport Performance is, how it is calculated, and methodology limitations.