Debugging the doc generation process

jazzband · Dec 23, 2021 · 4d19a7a · 4d19a7a
1 parent cd43f6e
commit 4d19a7a
Show file tree

Hide file tree

Showing 5 changed files with 86 additions and 76 deletions.
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -26,13 +26,14 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        if [ -f requirements/test.txt ]; then pip install -r requirements/dev.txt; fi
-    - name: Sphinx Pages
-      # You may pin to the exact commit or the version.
-      # uses: seanzhengw/sphinx-pages@70dd0557fc226cfcd41c617aec5e9ee4fce4afe2
-      uses: seanzhengw/sphinx-pages@d29427677b3b89c1b5311d9eb135fb4168f4ba4a
-      with:
-        # Token for the repo. Can be passed in using $\{{ secrets.GITHUB_TOKEN }}
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        # Auto create a README.md file at branch gh-pages root with repo/branch/commit links
-        source_dir: "doc_src"
+        pip install -r requirements/dev.txt
+        make pubdocs
+#    - name: Sphinx Pages
+#      # You may pin to the exact commit or the version.
+#      # uses: seanzhengw/sphinx-pages@70dd0557fc226cfcd41c617aec5e9ee4fce4afe2
+#      uses: seanzhengw/sphinx-pages@d29427677b3b89c1b5311d9eb135fb4168f4ba4a
+#      with:
+#        # Token for the repo. Can be passed in using $\{{ secrets.GITHUB_TOKEN }}
+#        github_token: ${{ secrets.GITHUB_TOKEN }}
+#        # Auto create a README.md file at branch gh-pages root with repo/branch/commit links
+#        source_dir: "doc_src"
diff --git a/.github/workflows/run-tests.yaml b/.github/workflows/run-tests.yaml
@@ -1,7 +1,7 @@
 name: Run Tox tests
-on:
-  - push
-  - pull_request
+#on:
+#  - push
+#  - pull_request
 
 jobs:
   build:

diff --git a/.gitignore b/.gitignore
@@ -67,6 +67,7 @@ cover/
 local_settings.py
 db.sqlite3
 db.sqlite3-journal
+dev.db
 
 # Flask stuff:
 instance/
@@ -168,9 +169,11 @@ output/*/index.html
 junit-*.xml
 flake8-errors.txt
 example/media/
+
 # Documentation building
 _build
 doc_src/api/categories*.rst
+docs
 
 RELEASE.txt
 site-packages

diff --git a/Makefile b/Makefile
@@ -1,3 +1,4 @@
+.PHONY: clean clean-test clean-pyc clean-build docs help
 .DEFAULT_GOAL := help
 
 RELEASE_KIND := patch
@@ -84,9 +85,12 @@ release-minor: set-release-minor-env-var release-helper  ## Release a new minor
 
 release-major: set-release-major-env-var release-helper  ## release a new major version: 1.1.1 -> 2.0.0
 
-documentation:
+docs:  ## generate Sphinx HTML documentation, including API docs
 	mkdir -p docs
 	rm -f doc_src/api/$(SOURCE_DIR)*.rst
 	ls -A1 docs | xargs -I {} rm -rf docs/{}
 	$(MAKE) -C doc_src clean html
 	cp -a doc_src/_build/html/. docs
+
+pubdocs: docs  ## Publish the documentation to GitHub
+	ghp-import -op docs
diff --git a/categories/templatetags/category_tags.py b/categories/templatetags/category_tags.py
@@ -112,21 +112,22 @@ def get_category_drilldown(parser, token):
     """
     Retrieves the specified category, its ancestors and its immediate children as an Iterable.
 
-    Syntax::
+    The basic syntax::
 
         {% get_category_drilldown "category name" [using "app.Model"] as varname %}
 
-    Example::
+    Example:
+        Using a string for the category name::
 
-        {% get_category_drilldown "/Grandparent/Parent" [using "app.Model"] as family %}
+            {% get_category_drilldown "/Grandparent/Parent" as family %}
 
-    or ::
+        or using a variable for the category::
 
-        {% get_category_drilldown category_obj as family %}
+            {% get_category_drilldown category_obj as family %}
 
-    Sets family to::
+        Sets family to::
 
-        Grandparent, Parent, Child 1, Child 2, Child n
+            Grandparent, Parent, Child 1, Child 2, Child n
 
     Args:
         parser: The Django template parser.
@@ -171,7 +172,9 @@ def breadcrumbs(category_string, separator=" > ", using="categories.category"):
     """
     Render breadcrumbs, using the ``categories/breadcrumbs.html`` template.
 
-    {% breadcrumbs category separator="::" using="categories.category" %}
+    The basic syntax::
+
+        {% breadcrumbs "category" [separator=" > "] [using="categories.category"] %}
 
     Args:
         category_string: A variable reference to or the name of the category to display
@@ -191,33 +194,34 @@ def display_drilldown_as_ul(category, using="categories.Category"):
     """
     Render the category with ancestors and children using the ``categories/ul_tree.html`` template.
 
-    Example::
+    Example:
+        The template code of::
 
-        {% display_drilldown_as_ul "/Grandparent/Parent" %}
+            {% display_drilldown_as_ul "/Grandparent/Parent" %}
 
-    or ::
+        or::
 
-        {% display_drilldown_as_ul category_obj %}
+            {% display_drilldown_as_ul category_obj %}
 
-    Returns::
+        might render as::
 
-        <ul>
-          <li><a href="/categories/">Top</a>
-          <ul>
-            <li><a href="/categories/grandparent/">Grandparent</a>
             <ul>
-              <li><a href="/categories/grandparent/parent/">Parent</a>
+              <li><a href="/categories/">Top</a>
               <ul>
-                <li><a href="/categories/grandparent/parent/child1">Child1</a></li>
-                <li><a href="/categories/grandparent/parent/child2">Child2</a></li>
-                <li><a href="/categories/grandparent/parent/child3">Child3</a></li>
+                <li><a href="/categories/grandparent/">Grandparent</a>
+                <ul>
+                  <li><a href="/categories/grandparent/parent/">Parent</a>
+                  <ul>
+                    <li><a href="/categories/grandparent/parent/child1">Child1</a></li>
+                    <li><a href="/categories/grandparent/parent/child2">Child2</a></li>
+                    <li><a href="/categories/grandparent/parent/child3">Child3</a></li>
+                  </ul>
+                  </li>
+                </ul>
+                </li>
               </ul>
               </li>
             </ul>
-            </li>
-          </ul>
-          </li>
-        </ul>
 
     Args:
         category: A variable reference to or the name of the category to display
@@ -239,23 +243,23 @@ def display_path_as_ul(category, using="categories.Category"):
     Render the category with ancestors, but no children using the ``categories/ul_tree.html`` template.
 
     Examples:
-        ```
-        {% display_path_as_ul "/Grandparent/Parent" %}
-        ```
-        ```
-        {% display_path_as_ul category_obj %}
-        ```
-
-    Output:
-        ```
-        <ul>
-            <li><a href="/categories/">Top</a>
+        The template code of::
+
+            {% display_path_as_ul "/Grandparent/Parent" %}
+
+        or::
+
+            {% display_path_as_ul category_obj %}
+
+        might render as::
+
             <ul>
-                <li><a href="/categories/grandparent/">Grandparent</a></li>
+                <li><a href="/categories/">Top</a>
+                <ul>
+                    <li><a href="/categories/grandparent/">Grandparent</a></li>
+                </ul>
+                </li>
             </ul>
-            </li>
-        </ul>
-        ```
 
     Args:
         category: A variable reference to or the name of the category to display
@@ -291,18 +295,16 @@ def get_top_level_categories(parser, token):
     """
     Retrieves an alphabetical list of all the categories that have no parents.
 
-    Usage:
+    The basic syntax is::
 
-        ```
         {% get_top_level_categories [using "app.Model"] as categories %}
-        ```
 
     Args:
         parser: The Django template parser.
         token: The tag contents
 
     Returns:
-         Returns an list of categories [<category>, <category>, <category, ...]
+         Returns a list of categories [<category>, <category>, <category, ...]
 
     Raises:
         TemplateSyntaxError: If a queryset isn't provided
@@ -379,10 +381,10 @@ def do_get_latest_objects_by_category(parser, token):
     """
     Get the latest objects by category.
 
-    Usage:
-        ```
+    The basic syntax is::
+
         {% get_latest_objects_by_category category app_name model_name set_name [date_field] [number] as [var_name] %}
-        ```
+
 
     Args:
         parser: The Django template parser.
@@ -477,21 +479,21 @@ def recursetree(parser, token):
     This tag will recursively render children into the template variable {{ children }}.
     Only one database query is required (children are cached for the whole tree)
 
-    Usage:
-        ```
-        <ul>
-            {% recursetree nodes %}
-                <li>
-                    {{ node.name }}
-                    {% if not node.is_leaf_node %}
-                        <ul>
-                            {{ children }}
-                        </ul>
-                    {% endif %}
-                </li>
-            {% endrecursetree %}
-        </ul>
-        ```
+    Example:
+        Basic usage example::
+
+            <ul>
+                {% recursetree nodes %}
+                    <li>
+                        {{ node.name }}
+                        {% if not node.is_leaf_node %}
+                            <ul>
+                                {{ children }}
+                            </ul>
+                        {% endif %}
+                    </li>
+                {% endrecursetree %}
+            </ul>
 
     Args:
         parser: The Django template parser.