Docs: how-to guides and clearer writing (#49)

* Fix link to blocked combo issue in README

* Move API reference material within reference sect

* Expand tutorials spiel

* Start writing how-to guides

* Expand population querist how-to

* Include how-to guides in top-level site

* Sort population type querist output

* Run population how-to with sorted outputs

* Reset index when sorting in population querist

* Remove QA document

So much of it is irrelevant to the work.

* Write how-to on querying features

* Reset indices on all metadata querists

* Rerun population type how-to

* Fix the category querist (#52)

* Migrate tests to area type category querist

The old implementation only serves area type category queries.

* Finish tests for area type category querist

* Write tests for remaining category querist methods

* Implement category querist

* Remove dictionary union operators

* Add category querist how-to

* Change area type category how-to to MSOA

Let's aim for highest coverage in our integration tests...

* Add sections to category how-to

* Add coverage checking to integration doctests

* Run doctests on Python 3.8 as well

* Add python version to quartodoc dependency

* Fix typo in qualification

* Add table how-to; skim some cream off tutorial

.docscoveragerc

@@ -0,0 +1,3 @@
+[report]
+exclude_also =
+    def _process_response

.github/workflows/tests.yml

@@ -34,12 +34,17 @@ jobs:
         run: |
           python -m pytest tests --cov=census21api --cov-fail-under=100
       - name: Test documentation
-        if: matrix.os == 'ubuntu-latest' && matrix.python-version == 3.11
+        if: matrix.os == 'ubuntu-latest'
         run: |
           python -m pip install ".[docs]"
           python -m doctest README.md
           python -m pytest docs \
-            --nbval --nbval-current-env --randomly-dont-reorganize
+            --nbval \
+            --nbval-current-env \
+            --randomly-dont-reorganize \
+            --cov=census21api \
+            --cov-config=.docscoveragerc \
+            --cov-fail-under=99
       - name: Install and run linters
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == 3.11
         run: |

README.md

@@ -87,9 +87,9 @@ contribution or opening an issue.
 
 ### Blocked dimension combinations
 
-Some combinations of columns (dimensions) cannot be queried at once. See #39
-for an example. This is a deliberate block put in place by the developers of
-the API.
+Some combinations of columns (dimensions) cannot be queried at once. See
+[#39](https://github.com/datasciencecampus/issues/39) for an example. This is a
+deliberate block put in place by the developers of the API.
 
 ### Some columns are missing
 

_quarto.yml

@@ -12,6 +12,8 @@ website:
         text: About
       - href: docs/tutorials/index.qmd
         text: Tutorials
+      - href: docs/how-to-guides/index.qmd
+        text: How-to guides
       - href: docs/reference/index.qmd
         text: Reference
     right:
@@ -25,8 +27,10 @@ website:
     left: >
       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.<br>
-      Built using [Quarto](https://quarto.org/).
+      except where otherwise stated.
+    center: >
+      Built using [Quarto](https://quarto.org/) and
+      [Diátaxis](https://diataxis.fr/).
 
 format:
   html:
@@ -37,10 +41,10 @@ format:
 quartodoc:
   title: API reference
   package: census21api
-  dir: docs/reference
+  dir: docs/reference/api
   sections:
     - title: CensusAPI
-      desc: Core class for connecting to the Census API.
+      desc: Core class for connecting to the Census API
       package: census21api.wrapper
       contents:
         - CensusAPI

docs/how-to-guides/index.qmd

@@ -0,0 +1,13 @@
+---
+title: How-to guides
+listing:
+    type: table
+    contents:
+        - "*.ipynb"
+    fields: [title, description]
+---
+
+This section of the documentation comprises bite-size, task-oriented guides on
+how to make different queries using `census21api`.
+
+<br>