diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index aa13e2b..4852979 100644 --- 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 index 5d979a8..ed93a00 100644 --- 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 index a8acde2..2948063 100644 --- 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 index ac0575b..b630b5f 100644 --- 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 index 460509a..cc4a579 100644 --- 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:: - 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 %} - ``` + The template code of:: + + {% display_path_as_ul "/Grandparent/Parent" %} + + or:: + + {% display_path_as_ul category_obj %} + + might render as:: - Output: - ``` - - ``` 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 [, , , , - {% recursetree nodes %} -
  • - {{ node.name }} - {% if not node.is_leaf_node %} -
      - {{ children }} -
    - {% endif %} -
    • - {% endrecursetree %} - - ``` + Example: + Basic usage example:: + +
      + {% recursetree nodes %} +
    • + {{ node.name }} + {% if not node.is_leaf_node %} +
        + {{ children }} +
      + {% endif %} +
      • + {% endrecursetree %} +
    Args: parser: The Django template parser.