diff --git a/mkdocs.yml b/mkdocs.yml index 66dadc81..f777f589 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,14 +18,20 @@ theme: default: material/tag features: + # render a breadcrumb navigation above the title of each page, which might make orientation easier for users visiting your documentation on devices with smaller screens. - navigation.path - - navigation.top + - navigation.top # back-to-top button shown when user, after scrolling down, starts to scroll up again. - navigation.footer # enables switching multiple tabs with the same name - content.tabs.link # renders copy button on code blocks - content.code.copy + - navigation.instant + # URL in the address bar is automatically updated with the active anchor as highlighted in the table of contents (right sidebar) + - navigation.tracking + - navigation.indexes + plugins: # Enable jinja inside your markdown files # - allows {% include %} statements @@ -58,7 +64,7 @@ plugins: # programmatically generate Nav Item: ie 'reference/' entry in Navigation - literate-nav: nav_file: SUMMARY.md - - section-index + # - section-index # Enable displaying at the bottom of pages the last date of modification! # uv add --optional docs 'mkdocs-git-revision-date-localized-plugin' diff --git a/pyproject.toml b/pyproject.toml index d92ebd8a..ccd4efae 100755 --- a/pyproject.toml +++ b/pyproject.toml @@ -126,7 +126,6 @@ docs = [ "mkdocs-macros-plugin>=1.3.7, <2.0.0", "mkdocs-material>=9.6.12, <10.0.0", "mkdocs-mermaid2-plugin>=1.2.1, <2.0.0", - "mkdocs-section-index==0.3.9", # mkdocstrings 0.26.1 is the last to support python3.8! "mkdocstrings==0.26.1", "mkdocstrings-python==1.11.1", diff --git a/scripts/gen_api_refs_pages.py b/scripts/gen_api_refs_pages.py index e1b16be2..1aa3d602 100644 --- a/scripts/gen_api_refs_pages.py +++ b/scripts/gen_api_refs_pages.py @@ -22,6 +22,7 @@ for path in sorted( x for x in src.rglob("*.py") if '{{ cookiecutter.project_slug }}' not in x.parts ): + # print(f"Processing {path}") ## 1. extract Relative path from Python File and remove suffix (.py) # EG src/biskotaki/cli.py --> biskotaki/cli _module_path = path.relative_to(src).with_suffix("") @@ -35,7 +36,6 @@ # Skip __main__ Files if parts[-1] == "__main__": - print(f"Skip Gen API Refs for file: {path}") continue # For __init__ Files dedicate an index.md file, instead of __init__.md diff --git a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/mkdocs.yml b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/mkdocs.yml index 69a5a609..f9311b1a 100644 --- a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/mkdocs.yml +++ b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/mkdocs.yml @@ -17,25 +17,43 @@ theme: default: material/tag features: + # render a breadcrumb navigation above the title of each page, which might make orientation easier for users visiting your documentation on devices with smaller screens. - navigation.path - - navigation.top + - navigation.top # back-to-top button shown when user, after scrolling down, starts to scroll - navigation.footer + # enables switching multiple tabs with the same name + - content.tabs.link + # renders copy button on code blocks + - content.code.copy + # make index.md landing page to collapsible sections (no need for sections-index 3rd-party plugin) + - navigation.indexes plugins: # Enable jinja inside your markdown files + # - allows {% raw %}{% include %}{% endraw %} statements + # - requires careful escape of double-braces in markdown + # - requires wrapping content between {% raw %}{%{% endraw %} raw {% raw %}%}{% endraw %} and {% raw %}{%{% endraw %} endraw {% raw %}%}{% endraw %} # https://github.com/fralau/mkdocs_macros_plugin - macros + # include_dir: docs/includes + # Authors need installation # - git-authors + + # Automated Tags - Page Generation - tags: tags_file: tags.md + # BASIC SEARCH PLUGIN - search + # MERMAID Render Support - mermaid2 + # Directives Provider for docstrings parsing - mkdocstrings - # gain the ability to tap-in to the build process + + # Tap-in to the build process and generate files with mkdocstrings directives - gen-files: # scripts allowing to programmatically generate .md content scripts: @@ -44,19 +62,94 @@ plugins: # programmatically generate Nav Item: ie 'reference/' entry in Navigation - literate-nav: nav_file: SUMMARY.md - - section-index markdown_extensions: - mkdocs-click - pymdownx.highlight - + + ### ADMONITIONS ### + # enabled block kelements such as example, note, info, warning, tip, etc + # https://squidfunk.github.io/mkdocs-material/reference/admonitions/ + - admonition + + ### SUPERFENCES ### + # arbitrary nesting of code and content blocks inside each other, + # including admonitions, tabs, lists and all other elements + # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences + # this custom fence defined below with name 'mermaid' is required + # to prevent superfences from breaking mermaid default syntax (3 backticks)! + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + + ### TABBED ### + # usage of content tabs, a simple way to group related content and + # code blocks under accessible tabs. + # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#tabbed + - pymdownx.tabbed: + alternate_style: true + + ### GRIDS with Grid Cards or Generic Cards ### + - attr_list + - md_in_html + + ### ICONS/EMOJIS ### + # https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#with-colors-docsstylesheetsextracss + # The following icon sets are bundled with Material for MkDocs: + # – Material Design: https://pictogrammers.com/library/mdi/ + # – FontAwesome : https://fontawesome.com/search?ic=free + # – Octicons : https://primer.style/octicons/ + # – Simple Icons : https://simpleicons.org/ + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + + ### On-HOVER TOOLTIP ### + # abbr by default supports tooltips on url links + - abbr + # if attr_list is also added, then tooltips on other html elements are supported as below: + # ie :material-information-outline:{ title="Important information" } + + # The Details extension supercharges the Admonition extension, making the resulting call-outs collapsible, allowing them to be opened and closed by the user. + # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#details + # example: ??? blahblah + # expanded example: ???+ blahblah + # if element is insise non-trivial content wrap in div with class markdown + - pymdownx.details + +###### SITE NAVIGATION ###### nav: - - Home: - - "Quick Start": index.md + ## Landing Page ## + - Home: index.md + + ## Motivation ## + # - Motivation: topics/why_this_package.md + + ## TUTORIALS ## + # - Tutorials: + # Landing Page + # - "tutorials/index.md" + + ## REFERENCES ## - API References: reference/ + + ## TOPICS/EXPLANATIONS ## - Topics: - - "Docker": build-process_DAG.md - - "CI/CD": cicd.md + + # Project Architecture + - "Architecture": "topics/arch.md" + + # Development (nested) topics: build process, CI/CD, etc. + - Development: + # Landing Page + - "topics/development/index.md" + # Nested Pages + - "Docker": "topics/development/build_process_DAG.md" + - "CI/CD": "topics/development/cicd.md" + + ## Automated Tags - Page Generation ## - tags: tags.md diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/assets/docker_off.png" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/assets/docker_off.png" deleted file mode 100644 index e709048f..00000000 Binary files "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/assets/docker_off.png" and /dev/null differ diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/build-process_DAG.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/build-process_DAG.md" deleted file mode 100644 index 30d2ae1a..00000000 --- "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/build-process_DAG.md" +++ /dev/null @@ -1,17 +0,0 @@ -## Docker Build Process DAG - -`docker build` possible execution paths. - -Flow Chart, of how exection navigates docker stages (see --target of docker build). - -If you run `docker build .` the `target` used by default is the `default_with_demo` Stage in the Graph. - -**Dockerfile: ./Dockerfile** - -{# we have include 'dockerfile_mermaid.md' statment below #} -{# intention is to leverage markdown imports, on docs build time #} -{# it should not affect dynamically the Generator behaviour #} - -{# so we must enusre that jinja does, treats below as literal, and not try to interpret #} - -{% raw %}{% include 'dockerfile_mermaid.md' %}{% endraw %} diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/cicd.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/cicd.md" deleted file mode 100644 index 5a610a0d..00000000 --- "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/cicd.md" +++ /dev/null @@ -1,14 +0,0 @@ ---- -tags: - - CICD ---- - -## CICD Pipeline, as Github Action Workflow - -### Variables to provide for `var` context - -Flow Chart, of Jobs Dependencies in the Pipeline. - -**config: ./.github/workflows/test.yaml** - -{% raw %}{% include 'cicd_mermaid.md' %}{% endraw %} diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/cicd_mermaid.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/cicd_mermaid.md" deleted file mode 100644 index 974b6b01..00000000 --- "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/cicd_mermaid.md" +++ /dev/null @@ -1,24 +0,0 @@ -{% if cookiecutter.cicd == "stable" %}```mermaid -graph LR; - set_github_outputs --> test_suite - test_suite --> codecov_coverage_host - set_github_outputs --> docker_build - test_suite --> docker_build - set_github_outputs --> check_which_git_branch_we_are_on - test_suite --> pypi_publish - check_which_git_branch_we_are_on --> pypi_publish - set_github_outputs --> lint - set_github_outputs --> docs - set_github_outputs --> code_visualization -```{% elif cookiecutter.cicd == "experimental" %}```mermaid -graph LR; - test_n_build - test_n_build --> codecov_coverage_host - test_n_build --> docker_build - lint - docs - code_visualization - test_n_build --> signal_deploy - signal_deploy --> pypi_publish - signal_deploy --> gh_release -```{% endif %} diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dev_guides/docker.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dev_guides/docker.md" deleted file mode 100644 index 19731b3d..00000000 --- "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dev_guides/docker.md" +++ /dev/null @@ -1,40 +0,0 @@ -# Do Docker-related stuff - -
- Docker on CI - - ## How to prevent any Image from being published to Dockerhub - - 1. Open your `.github/workflows/test.yaml`, and look for the **Worfklow Variables** - - **Worfklow Variables** are defined in the `env` *section* - - 2. Check the *value* of the `DOCKER_JOB_ON` **Worfklow Variable** - - [this is line is not rendered; markdown comment]: # - - ![Docker OFF](../assets/docker_off.png) - - 3. If *value* is **false**, then we are OK. - - 4. If not, set value* to **false** - - ```shell - git add .github/workflows/test.yaml - git commit "ci: emphemerally prevent any Image Build and Dockerhub Publish" - ``` - - Now, it is **guaranteed**, that **NO** Dockerhub Publish will happen, - by any Pipeline subsequent `trigger`, aka `git events` (ie `git push`) fired. - - **Info**: the `DOCKER_JOB_ON` is a top-level Gate to all Docker-related in CI. - Only, if `DOCKER_JOB_ON` is **true**, any image build and publish can be ever considered. - - -
- - -### References - -- [https://automated-workflows.readthedocs.io/en/main/guide_setup_cicd](https://automated-workflows.readthedocs.io/en/main/guide_setup_cicd/) -- [https://automated-workflows.readthedocs.io/en/main/ref_docker](https://automated-workflows.readthedocs.io/en/main/ref_docker/) diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dev_guides/index.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dev_guides/index.md" deleted file mode 100644 index 7949cf41..00000000 --- "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dev_guides/index.md" +++ /dev/null @@ -1,38 +0,0 @@ -# How-To Guides for Development - -This section includes practical, *how-to* guides, for a **developer** to achieve something. -Guides on how to **run tests** against your code, how to **publish to PyPI**, how to build -a Docker Image and **publish it to Dockerhub**, how to do `Static Code Analysis`, etc. - - -## How to prevent any Image from being published to Dockerhub - -1. Open your `.github/workflows/test.yaml`, and look for the **Worfklow Variables** - - **Worfklow Variables** are defined in the `env` *section* - -2. Check the *value* of the `DOCKER_JOB_ON` **Worfklow Variable** - - [this is line is not rendered; markdown comment]: # - - ![Docker OFF](../assets/docker_off.png) - -3. If *value* is **false**, then we are OK. - -4. If not, set value* to **false** - - ```shell - git add .github/workflows/test.yaml - git commit "ci: emphemerally prevent any Image Build and Dockerhub Publish" - ``` - -Now, it is **guaranteed**, that **NO** Dockerhub Publish will happen, -by any Pipeline subsequent `trigger`, aka `git events` (ie `git push`) fired. - -**Info**: the `DOCKER_JOB_ON` is a top-level Gate to all Docker-related in CI. -Only, if `DOCKER_JOB_ON` is **true**, any image build and publish can be ever considered. - -### References - -- https://automated-workflows.readthedocs.io/en/main/guide_setup_cicd/ -- https://automated-workflows.readthedocs.io/en/main/ref_docker/ diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/index.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/index.md" index 950f5372..ec53d19f 100644 --- "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/index.md" +++ "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/index.md" @@ -1,7 +1,73 @@ # Welcome to {{ cookiecutter.project_name }} Documentation! +[//]: # (Render a few important badges: CI/CD Status, RTD, Coverage, Latest Tag/Sem Ver) + {{ cookiecutter.project_name }} is an open source TODO +[//]: # (Same a few words about what this does) + +[//]: # (Maybe state Goal and/or small motivation note) + +[//]: # (Leverage Mermaid to show high of what happens) + +[//]: # (Ideally record video with demo and embed here) + ## Quick-start TODO + +## :material-book-open: Documentation + +Read about how to use the `{{ cookiecutter.pkg_name }}` package, understand its features +and capabilities. + +Learn how to use the `{{ cookiecutter.pkg_name }}` package, achieve goals leverating understand its features +and capabilities. + + +
+ + +- :fontawesome-regular-circle-play:{ .lg .middle } __`How-to` Guides__ + + --- + + Step-by-step `Guides` that leverage **{{ cookiecutter.pkg_name }}** to achieve `Goals`, such as: + + - TODO 1 + - TODO 2 + + [:octicons-arrow-right-24: :material-rocket-launch: `Install`, `Run`, `Use`](./guides/index.md) + + +- :material-application-brackets-outline:{ .lg .middle } __API References__ + + --- + [//]: # (link ./reference/CLI.md does not exist yet, it is generate at docs build-time) + [:octicons-arrow-right-24: :material-console:{ .lg .middle } {{ cookiecutter.pkg_name|replace('_', '-') }} CLI](./reference/CLI.md) + + [//]: # (link ./reference/{{ cookiecutter.pkg_name }}.md does not exist yet, it is generate at docs build-time) + [:octicons-arrow-right-24: :material-language-python: API Refs](./reference/{{ cookiecutter.pkg_name }}) + + +- :fontawesome-solid-book-open:{ .lg .middle } __Topics__ + + --- + + **Explanations / Topics** + + [:octicons-arrow-right-24: :material-language-python: Architecture ](./topics/arch.md) + + [//]: # (Add important Topics here) + + +- :fontawesome-solid-book-open:{ .lg .middle } __Development Topics__ + + --- + + **Topics / Explanations** on Development + + [:octicons-arrow-right-24: :material-hammer-screwdriver: Development Topics ](./topics/development/index.md) + + +
diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/arch.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/arch.md" new file mode 100644 index 00000000..1b90979c --- /dev/null +++ "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/arch.md" @@ -0,0 +1,51 @@ +# Software Architecture + +[//]: # (this is a comment) +[//]: # (Description of what is this Page) + +Here you can find the software architecture of the project. + +## Module Dependencies + +[//]: # (Description of what is this Section) + +Here you can find the dependencies between the modules of the project. + +The dependencies are Visualized as a Graph, where Nodes are the modules and the Edges are python ``import`` statements. + +The dependencies are visualized, after running the following command: + +```sh +tox -e pydeps +``` + +!!! Tip + + Right-click and open image in new Tab for better inspection + +### First-party Dependencies + +[//]: # (Inner Python Imports SVG Graph) + +![First-party Dependencies](../assets/deps_inner.svg) + + +### First and Third party Dependencies + +[//]: # (First-Party with 3rd-party having all incoming edges to our individual Modules) + +![All Dependencies - C](../assets/deps_all.svg) + + +### 1st+3rd party Deps - 1st as Cluster + +[//]: # ("Boxed" First-Party with 3rd-party having all incoming edges to our Box) + +![All Dependencies - B](../assets/deps_ktc.svg) + + +### 1st+3rd party Deps - 1st+3rd as Cluster + +[//]: # ("Boxed" First-Party with 3rd-party having 1 incoming edge to our Box) + +![All Dependencies - A](../assets/deps_ktc-mcs_2.svg) diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/build_process_DAG.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/build_process_DAG.md" new file mode 100644 index 00000000..709dc654 --- /dev/null +++ "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/build_process_DAG.md" @@ -0,0 +1,20 @@ +## Docker Build Process DAG + +> Understand how we leverage `Docker` in the build process. + +The project features a `Dockerfile`, designed for + +- multi-stage builds +- parallel stage building (assuming appropriate build backend) +- size minimization of the produced `Docker` image +- minimization of vulerabilities + +## Dockerfile visualized as Directed Acyclic Graph (DAG) + +> Understand the execution path of `docker build`, via **DAG visualization** + +{% raw %}{% include 'topics/development/dockerfile_mermaid.md' %}{% endraw %} + +- `solid boxes` represent distinct docker **stages** and their *aliases* +- `solid arrows` represent **stage dependencies**; `FROM a AS b` type of instructions +- `dotted arrows` represent **stage COPY**: `COPY --from=a /path /path` type of instructions diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/cicd.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/cicd.md" new file mode 100644 index 00000000..5341e037 --- /dev/null +++ "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/cicd.md" @@ -0,0 +1,28 @@ +--- +tags: + - CICD +--- + +## CI/CD Pipeline + +> Understand what Jobs are part of the CI/CD Pipeline + +**CI/CD Pipeline** is implemented as `Github Actions Workflow` in a YAML file format. + +### Workflow of Jobs: visualized as a Directed Acyclic Graph (DAG) + +> Understand the Job Dependencies at "compile time" + +**YAML Workflow: ./.github/workflows/cicd.yml** + +{% raw %}{% include 'topics/development/cicd_mermaid.md' %}{% endraw %} + +- `solid boxes` represent **Jobs** declared in the `jobs` array of the YAML Workflow +- `solid arrows` represent **Job Dependencies**; `job_A.needs: [job_b, job_c]` type of yaml objects + + +[//]: # (TODO add section to EXPLAIN the CI/CD Pipeline at runtime) + +[//]: # (TODO make screenshot of CI Server run and paste here) + +[//]: # (TODO add link to live CI server Pipeline RUNS) diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/cicd_mermaid.md "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/cicd_mermaid.md" similarity index 100% rename from tests/data/snapshots/biskotaki-gold-standard/docs/cicd_mermaid.md rename to "src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/cicd_mermaid.md" diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dockerfile_mermaid.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/dockerfile_mermaid.md" similarity index 100% rename from "src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dockerfile_mermaid.md" rename to "src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/dockerfile_mermaid.md" diff --git "a/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/index.md" "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/index.md" new file mode 100644 index 00000000..5a026902 --- /dev/null +++ "b/src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == \"mkdocs\" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/index.md" @@ -0,0 +1,35 @@ +# Development +Here you will find topics related to `Development`, the `build`, and the +`CI/CD` Pipeline design of the **Biskotaki** open-source project. + + +
+ + +- :material-docker:{ .lg .middle } __Docker__ + + --- + + Dockerfile design, Build Process + + [:octicons-arrow-right-24: Topic ](./build_process_DAG.md) + + +- :simple-githubactions:{ .lg .middle } __CI/CD Pipeline__ + + --- + + Github Actions Workflow of Jobs, visualized as a DAG + + [:octicons-arrow-right-24: Topic ](./cicd.md) + + +- :material-state-machine:{ .lg .middle } __Git Ops Processes__ + + --- + + Step-by-step Processes, leveraging `git` and `CI` for **Releasing changes** + + [:octicons-arrow-right-24: Docs ](./gitops/) + +
diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/assets/docker_off.png b/tests/data/snapshots/biskotaki-gold-standard/docs/assets/docker_off.png deleted file mode 100644 index e709048f..00000000 Binary files a/tests/data/snapshots/biskotaki-gold-standard/docs/assets/docker_off.png and /dev/null differ diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/build-process_DAG.md b/tests/data/snapshots/biskotaki-gold-standard/docs/build-process_DAG.md deleted file mode 100644 index 2b0d4bdf..00000000 --- a/tests/data/snapshots/biskotaki-gold-standard/docs/build-process_DAG.md +++ /dev/null @@ -1,17 +0,0 @@ -## Docker Build Process DAG - -`docker build` possible execution paths. - -Flow Chart, of how exection navigates docker stages (see --target of docker build). - -If you run `docker build .` the `target` used by default is the `default_with_demo` Stage in the Graph. - -**Dockerfile: ./Dockerfile** - - - - - - - -{% include 'dockerfile_mermaid.md' %} diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/cicd.md b/tests/data/snapshots/biskotaki-gold-standard/docs/cicd.md deleted file mode 100644 index c3a10be7..00000000 --- a/tests/data/snapshots/biskotaki-gold-standard/docs/cicd.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -tags: - - CICD ---- - -## CICD Pipeline, as Github Action Workflow - -### Variables to provide for `var` context - -Flow Chart, of Jobs Dependencies in the Pipeline. - -**config: ./.github/workflows/test.yaml** - -{% include 'cicd_mermaid.md' %} diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/dev_guides/docker.md b/tests/data/snapshots/biskotaki-gold-standard/docs/dev_guides/docker.md deleted file mode 100644 index 19731b3d..00000000 --- a/tests/data/snapshots/biskotaki-gold-standard/docs/dev_guides/docker.md +++ /dev/null @@ -1,40 +0,0 @@ -# Do Docker-related stuff - -
- Docker on CI - - ## How to prevent any Image from being published to Dockerhub - - 1. Open your `.github/workflows/test.yaml`, and look for the **Worfklow Variables** - - **Worfklow Variables** are defined in the `env` *section* - - 2. Check the *value* of the `DOCKER_JOB_ON` **Worfklow Variable** - - [this is line is not rendered; markdown comment]: # - - ![Docker OFF](../assets/docker_off.png) - - 3. If *value* is **false**, then we are OK. - - 4. If not, set value* to **false** - - ```shell - git add .github/workflows/test.yaml - git commit "ci: emphemerally prevent any Image Build and Dockerhub Publish" - ``` - - Now, it is **guaranteed**, that **NO** Dockerhub Publish will happen, - by any Pipeline subsequent `trigger`, aka `git events` (ie `git push`) fired. - - **Info**: the `DOCKER_JOB_ON` is a top-level Gate to all Docker-related in CI. - Only, if `DOCKER_JOB_ON` is **true**, any image build and publish can be ever considered. - - -
- - -### References - -- [https://automated-workflows.readthedocs.io/en/main/guide_setup_cicd](https://automated-workflows.readthedocs.io/en/main/guide_setup_cicd/) -- [https://automated-workflows.readthedocs.io/en/main/ref_docker](https://automated-workflows.readthedocs.io/en/main/ref_docker/) diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/dev_guides/index.md b/tests/data/snapshots/biskotaki-gold-standard/docs/dev_guides/index.md deleted file mode 100644 index 7949cf41..00000000 --- a/tests/data/snapshots/biskotaki-gold-standard/docs/dev_guides/index.md +++ /dev/null @@ -1,38 +0,0 @@ -# How-To Guides for Development - -This section includes practical, *how-to* guides, for a **developer** to achieve something. -Guides on how to **run tests** against your code, how to **publish to PyPI**, how to build -a Docker Image and **publish it to Dockerhub**, how to do `Static Code Analysis`, etc. - - -## How to prevent any Image from being published to Dockerhub - -1. Open your `.github/workflows/test.yaml`, and look for the **Worfklow Variables** - - **Worfklow Variables** are defined in the `env` *section* - -2. Check the *value* of the `DOCKER_JOB_ON` **Worfklow Variable** - - [this is line is not rendered; markdown comment]: # - - ![Docker OFF](../assets/docker_off.png) - -3. If *value* is **false**, then we are OK. - -4. If not, set value* to **false** - - ```shell - git add .github/workflows/test.yaml - git commit "ci: emphemerally prevent any Image Build and Dockerhub Publish" - ``` - -Now, it is **guaranteed**, that **NO** Dockerhub Publish will happen, -by any Pipeline subsequent `trigger`, aka `git events` (ie `git push`) fired. - -**Info**: the `DOCKER_JOB_ON` is a top-level Gate to all Docker-related in CI. -Only, if `DOCKER_JOB_ON` is **true**, any image build and publish can be ever considered. - -### References - -- https://automated-workflows.readthedocs.io/en/main/guide_setup_cicd/ -- https://automated-workflows.readthedocs.io/en/main/ref_docker/ diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/index.md b/tests/data/snapshots/biskotaki-gold-standard/docs/index.md index a1792b64..0259da0b 100644 --- a/tests/data/snapshots/biskotaki-gold-standard/docs/index.md +++ b/tests/data/snapshots/biskotaki-gold-standard/docs/index.md @@ -1,7 +1,73 @@ # Welcome to Biskotaki Gold Standard Documentation! +[//]: # (Render a few important badges: CI/CD Status, RTD, Coverage, Latest Tag/Sem Ver) + Biskotaki Gold Standard is an open source TODO +[//]: # (Same a few words about what this does) + +[//]: # (Maybe state Goal and/or small motivation note) + +[//]: # (Leverage Mermaid to show high of what happens) + +[//]: # (Ideally record video with demo and embed here) + ## Quick-start TODO + +## :material-book-open: Documentation + +Read about how to use the `biskotakigold` package, understand its features +and capabilities. + +Learn how to use the `biskotakigold` package, achieve goals leverating understand its features +and capabilities. + + +
+ + +- :fontawesome-regular-circle-play:{ .lg .middle } __`How-to` Guides__ + + --- + + Step-by-step `Guides` that leverage **biskotakigold** to achieve `Goals`, such as: + + - TODO 1 + - TODO 2 + + [:octicons-arrow-right-24: :material-rocket-launch: `Install`, `Run`, `Use`](./guides/index.md) + + +- :material-application-brackets-outline:{ .lg .middle } __API References__ + + --- + [//]: # (link ./reference/CLI.md does not exist yet, it is generate at docs build-time) + [:octicons-arrow-right-24: :material-console:{ .lg .middle } biskotakigold CLI](./reference/CLI.md) + + [//]: # (link ./reference/biskotakigold.md does not exist yet, it is generate at docs build-time) + [:octicons-arrow-right-24: :material-language-python: API Refs](./reference/biskotakigold) + + +- :fontawesome-solid-book-open:{ .lg .middle } __Topics__ + + --- + + **Explanations / Topics** + + [:octicons-arrow-right-24: :material-language-python: Architecture ](./topics/arch.md) + + [//]: # (Add important Topics here) + + +- :fontawesome-solid-book-open:{ .lg .middle } __Development Topics__ + + --- + + **Topics / Explanations** on Development + + [:octicons-arrow-right-24: :material-hammer-screwdriver: Development Topics ](./topics/development/index.md) + + +
diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/topics/arch.md b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/arch.md new file mode 100644 index 00000000..1b90979c --- /dev/null +++ b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/arch.md @@ -0,0 +1,51 @@ +# Software Architecture + +[//]: # (this is a comment) +[//]: # (Description of what is this Page) + +Here you can find the software architecture of the project. + +## Module Dependencies + +[//]: # (Description of what is this Section) + +Here you can find the dependencies between the modules of the project. + +The dependencies are Visualized as a Graph, where Nodes are the modules and the Edges are python ``import`` statements. + +The dependencies are visualized, after running the following command: + +```sh +tox -e pydeps +``` + +!!! Tip + + Right-click and open image in new Tab for better inspection + +### First-party Dependencies + +[//]: # (Inner Python Imports SVG Graph) + +![First-party Dependencies](../assets/deps_inner.svg) + + +### First and Third party Dependencies + +[//]: # (First-Party with 3rd-party having all incoming edges to our individual Modules) + +![All Dependencies - C](../assets/deps_all.svg) + + +### 1st+3rd party Deps - 1st as Cluster + +[//]: # ("Boxed" First-Party with 3rd-party having all incoming edges to our Box) + +![All Dependencies - B](../assets/deps_ktc.svg) + + +### 1st+3rd party Deps - 1st+3rd as Cluster + +[//]: # ("Boxed" First-Party with 3rd-party having 1 incoming edge to our Box) + +![All Dependencies - A](../assets/deps_ktc-mcs_2.svg) diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/build_process_DAG.md b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/build_process_DAG.md new file mode 100644 index 00000000..e283c268 --- /dev/null +++ b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/build_process_DAG.md @@ -0,0 +1,20 @@ +## Docker Build Process DAG + +> Understand how we leverage `Docker` in the build process. + +The project features a `Dockerfile`, designed for + +- multi-stage builds +- parallel stage building (assuming appropriate build backend) +- size minimization of the produced `Docker` image +- minimization of vulerabilities + +## Dockerfile visualized as Directed Acyclic Graph (DAG) + +> Understand the execution path of `docker build`, via **DAG visualization** + +{% include 'topics/development/dockerfile_mermaid.md' %} + +- `solid boxes` represent distinct docker **stages** and their *aliases* +- `solid arrows` represent **stage dependencies**; `FROM a AS b` type of instructions +- `dotted arrows` represent **stage COPY**: `COPY --from=a /path /path` type of instructions diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/cicd.md b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/cicd.md new file mode 100644 index 00000000..359a8a16 --- /dev/null +++ b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/cicd.md @@ -0,0 +1,28 @@ +--- +tags: + - CICD +--- + +## CI/CD Pipeline + +> Understand what Jobs are part of the CI/CD Pipeline + +**CI/CD Pipeline** is implemented as `Github Actions Workflow` in a YAML file format. + +### Workflow of Jobs: visualized as a Directed Acyclic Graph (DAG) + +> Understand the Job Dependencies at "compile time" + +**YAML Workflow: ./.github/workflows/cicd.yml** + +{% include 'topics/development/cicd_mermaid.md' %} + +- `solid boxes` represent **Jobs** declared in the `jobs` array of the YAML Workflow +- `solid arrows` represent **Job Dependencies**; `job_A.needs: [job_b, job_c]` type of yaml objects + + +[//]: # (TODO add section to EXPLAIN the CI/CD Pipeline at runtime) + +[//]: # (TODO make screenshot of CI Server run and paste here) + +[//]: # (TODO add link to live CI server Pipeline RUNS) diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/cicd_mermaid.md b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/cicd_mermaid.md new file mode 100644 index 00000000..309a4305 --- /dev/null +++ b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/cicd_mermaid.md @@ -0,0 +1,12 @@ +```mermaid +graph LR; + test_n_build + test_n_build --> codecov_coverage_host + test_n_build --> docker_build + lint + docs + code_visualization + test_n_build --> signal_deploy + signal_deploy --> pypi_publish + signal_deploy --> gh_release +``` diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/dockerfile_mermaid.md b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/dockerfile_mermaid.md similarity index 100% rename from tests/data/snapshots/biskotaki-gold-standard/docs/dockerfile_mermaid.md rename to tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/dockerfile_mermaid.md diff --git a/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/index.md b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/index.md new file mode 100644 index 00000000..5a026902 --- /dev/null +++ b/tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/index.md @@ -0,0 +1,35 @@ +# Development +Here you will find topics related to `Development`, the `build`, and the +`CI/CD` Pipeline design of the **Biskotaki** open-source project. + + +
+ + +- :material-docker:{ .lg .middle } __Docker__ + + --- + + Dockerfile design, Build Process + + [:octicons-arrow-right-24: Topic ](./build_process_DAG.md) + + +- :simple-githubactions:{ .lg .middle } __CI/CD Pipeline__ + + --- + + Github Actions Workflow of Jobs, visualized as a DAG + + [:octicons-arrow-right-24: Topic ](./cicd.md) + + +- :material-state-machine:{ .lg .middle } __Git Ops Processes__ + + --- + + Step-by-step Processes, leveraging `git` and `CI` for **Releasing changes** + + [:octicons-arrow-right-24: Docs ](./gitops/) + +
diff --git a/tests/data/snapshots/biskotaki-gold-standard/mkdocs.yml b/tests/data/snapshots/biskotaki-gold-standard/mkdocs.yml index d26fb136..dc581b42 100644 --- a/tests/data/snapshots/biskotaki-gold-standard/mkdocs.yml +++ b/tests/data/snapshots/biskotaki-gold-standard/mkdocs.yml @@ -17,25 +17,43 @@ theme: default: material/tag features: + # render a breadcrumb navigation above the title of each page, which might make orientation easier for users visiting your documentation on devices with smaller screens. - navigation.path - - navigation.top + - navigation.top # back-to-top button shown when user, after scrolling down, starts to scroll - navigation.footer + # enables switching multiple tabs with the same name + - content.tabs.link + # renders copy button on code blocks + - content.code.copy + # make index.md landing page to collapsible sections (no need for sections-index 3rd-party plugin) + - navigation.indexes plugins: # Enable jinja inside your markdown files + # - allows {% include %} statements + # - requires careful escape of double-braces in markdown + # - requires wrapping content between {% raw %} and {% endraw %} # https://github.com/fralau/mkdocs_macros_plugin - macros + # include_dir: docs/includes + # Authors need installation # - git-authors + + # Automated Tags - Page Generation - tags: tags_file: tags.md + # BASIC SEARCH PLUGIN - search + # MERMAID Render Support - mermaid2 + # Directives Provider for docstrings parsing - mkdocstrings - # gain the ability to tap-in to the build process + + # Tap-in to the build process and generate files with mkdocstrings directives - gen-files: # scripts allowing to programmatically generate .md content scripts: @@ -44,19 +62,94 @@ plugins: # programmatically generate Nav Item: ie 'reference/' entry in Navigation - literate-nav: nav_file: SUMMARY.md - - section-index markdown_extensions: - mkdocs-click - pymdownx.highlight - + + ### ADMONITIONS ### + # enabled block kelements such as example, note, info, warning, tip, etc + # https://squidfunk.github.io/mkdocs-material/reference/admonitions/ + - admonition + + ### SUPERFENCES ### + # arbitrary nesting of code and content blocks inside each other, + # including admonitions, tabs, lists and all other elements + # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences + # this custom fence defined below with name 'mermaid' is required + # to prevent superfences from breaking mermaid default syntax (3 backticks)! + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + + ### TABBED ### + # usage of content tabs, a simple way to group related content and + # code blocks under accessible tabs. + # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#tabbed + - pymdownx.tabbed: + alternate_style: true + + ### GRIDS with Grid Cards or Generic Cards ### + - attr_list + - md_in_html + + ### ICONS/EMOJIS ### + # https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#with-colors-docsstylesheetsextracss + # The following icon sets are bundled with Material for MkDocs: + # – Material Design: https://pictogrammers.com/library/mdi/ + # – FontAwesome : https://fontawesome.com/search?ic=free + # – Octicons : https://primer.style/octicons/ + # – Simple Icons : https://simpleicons.org/ + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + + ### On-HOVER TOOLTIP ### + # abbr by default supports tooltips on url links + - abbr + # if attr_list is also added, then tooltips on other html elements are supported as below: + # ie :material-information-outline:{ title="Important information" } + + # The Details extension supercharges the Admonition extension, making the resulting call-outs collapsible, allowing them to be opened and closed by the user. + # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#details + # example: ??? blahblah + # expanded example: ???+ blahblah + # if element is insise non-trivial content wrap in div with class markdown + - pymdownx.details + +###### SITE NAVIGATION ###### nav: - - Home: - - "Quick Start": index.md + ## Landing Page ## + - Home: index.md + + ## Motivation ## + # - Motivation: topics/why_this_package.md + + ## TUTORIALS ## + # - Tutorials: + # Landing Page + # - "tutorials/index.md" + + ## REFERENCES ## - API References: reference/ + + ## TOPICS/EXPLANATIONS ## - Topics: - - "Docker": build-process_DAG.md - - "CI/CD": cicd.md + + # Project Architecture + - "Architecture": "topics/arch.md" + + # Development (nested) topics: build process, CI/CD, etc. + - Development: + # Landing Page + - "topics/development/index.md" + # Nested Pages + - "Docker": "topics/development/build_process_DAG.md" + - "CI/CD": "topics/development/cicd.md" + + ## Automated Tags - Page Generation ## - tags: tags.md diff --git a/tests/test_build_backend_sdist.py b/tests/test_build_backend_sdist.py index ca59d4a1..dcf3baa6 100644 --- a/tests/test_build_backend_sdist.py +++ b/tests/test_build_backend_sdist.py @@ -49,14 +49,14 @@ def sdist_expected_correct_file_structure(): 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/.readthedocs.yml', 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/Dockerfile', 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/MANIFEST.in', - 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/assets/docker_off.png', - 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/build-process_DAG.md', - 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/cicd.md', - 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/cicd_mermaid.md', - 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dev_guides/docker.md', - 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dev_guides/index.md', - 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/dockerfile_mermaid.md', + # MKDOCS 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/index.md', + 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/arch.md', + 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/build_process_DAG.md', + 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/cicd.md', + 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/cicd_mermaid.md', + 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/dockerfile_mermaid.md', + 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/topics/development/index.md', 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "mkdocs" %}docs{% else %}PyGen_TO_DELETE{% endif %}/tags.md', 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "sphinx" %}docs{% else %}PyGen_TO_DELETE{% endif %}/Makefile', 'src/cookiecutter_python/{{ cookiecutter.project_slug }}/{% if cookiecutter.docs_builder == "sphinx" %}docs{% else %}PyGen_TO_DELETE{% endif %}/conf.py', @@ -170,14 +170,14 @@ def sdist_expected_correct_file_structure(): 'tests/data/snapshots/biskotaki-gold-standard/CHANGELOG.rst', 'tests/data/snapshots/biskotaki-gold-standard/CONTRIBUTING.md', 'tests/data/snapshots/biskotaki-gold-standard/Dockerfile', - 'tests/data/snapshots/biskotaki-gold-standard/docs/assets/docker_off.png', - 'tests/data/snapshots/biskotaki-gold-standard/docs/build-process_DAG.md', - 'tests/data/snapshots/biskotaki-gold-standard/docs/cicd.md', - 'tests/data/snapshots/biskotaki-gold-standard/docs/cicd_mermaid.md', - 'tests/data/snapshots/biskotaki-gold-standard/docs/dev_guides/docker.md', - 'tests/data/snapshots/biskotaki-gold-standard/docs/dev_guides/index.md', - 'tests/data/snapshots/biskotaki-gold-standard/docs/dockerfile_mermaid.md', + # MKDOCS Docs dir 'tests/data/snapshots/biskotaki-gold-standard/docs/index.md', + 'tests/data/snapshots/biskotaki-gold-standard/docs/topics/arch.md', + 'tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/build_process_DAG.md', + 'tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/cicd.md', + 'tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/cicd_mermaid.md', + 'tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/dockerfile_mermaid.md', + 'tests/data/snapshots/biskotaki-gold-standard/docs/topics/development/index.md', 'tests/data/snapshots/biskotaki-gold-standard/docs/tags.md', 'tests/data/snapshots/biskotaki-gold-standard/LICENSE', 'tests/data/snapshots/biskotaki-gold-standard/mkdocs.yml', diff --git a/tests/test_gold_standard.py b/tests/test_gold_standard.py index 8cd93fc5..17a16b2f 100644 --- a/tests/test_gold_standard.py +++ b/tests/test_gold_standard.py @@ -46,16 +46,14 @@ def gen_gs_project( assert gen_project_dir.exists() assert gen_project_dir.is_dir() assert (gen_project_dir / 'src').exists() and (gen_project_dir / 'src').is_dir() - # Ad-hoc sanity checks that docs folder contains all sub-dirs and nested files + + # sanity checks on docs folder assert (gen_project_dir / 'docs').exists() + assert (gen_project_dir / 'docs').is_dir() + + # sanity check that cleanup of docs folder is done assert not (gen_project_dir / 'docs-mkdocs').exists() assert not (gen_project_dir / 'docs-sphinx').exists() - assert (gen_project_dir / 'docs').is_dir() - assert (gen_project_dir / 'docs' / 'assets').exists() - assert (gen_project_dir / 'docs' / 'assets').is_dir() - assert (gen_project_dir / 'docs' / 'dev_guides').exists() - assert (gen_project_dir / 'docs' / 'dev_guides' / 'docker.md').exists() - assert (gen_project_dir / 'docs' / 'dev_guides' / 'docker.md').is_file() ## Logging file created - Assertions ## from cookiecutter_python._logging_config import FILE_TARGET_LOGS @@ -139,11 +137,18 @@ def _compare_file_content(runtime_file: Path, snap_file: Path): runtime_file_content = runtime_file.read_text().splitlines() snap_file_content = snap_file.read_text().splitlines() + # find common parts of a above Path objects + common_parts = set(runtime_file.parts).intersection(set(snap_file.parts)) + + # use existing part to order the set + ordered_parts: t.Tuple = tuple([x for x in snap_file.parts if x in common_parts]) + for line_index, line_pair in enumerate(zip(runtime_file_content, snap_file_content)): assert line_pair[0] == line_pair[1], ( f"File: {runtime_file.relative_to(runtime_file.parent)} has different content at Runtime than in Snapshot\n" + f"Relative (sub) path: {Path(*ordered_parts).resolve()}\n" f"Line Index: {line_index}\n" - f"Line Runtime: {line_pair[0]}\n" + f"Line Runtime : {line_pair[0]}\n" f"Line Snapshot: {line_pair[1]}\n" ) assert len(runtime_file_content) == len(snap_file_content) @@ -203,12 +208,6 @@ def test_gs_matches_runtime( import sys running_on_windows: bool = sys.platform.startswith("win") - # exception misbehaviour fixed on Windows? - import os - - has_developer_fixed_windows_mishap: bool = ( - os.environ.get("BUG_LOG_DEL_WIN") != "permission_error" - ) # This is useful for local development, to make the tests more reliable snap_relative_paths_set = set( @@ -225,6 +224,7 @@ def test_gs_matches_runtime( 'settings.json', '.tox', '.pytest_cache', + 'del-env', } for p in x.parts ] @@ -234,9 +234,7 @@ def test_gs_matches_runtime( ) snap_relative_paths_set = set([x for x in snap_relative_paths_set if x.name != 'reqs.txt']) - if has_developer_fixed_windows_mishap: - assert runtime_relative_paths_set == snap_relative_paths_set - elif running_on_windows: # there is a log mishappening that we exists on windows + if running_on_windows: # there is a log mishappening that we exists on windows from cookiecutter_python._logging_config import ( FILE_TARGET_LOGS as LOG_FILE_NAME, ) diff --git a/uv.lock b/uv.lock index 02bf5d5a..7e49097d 100644 --- a/uv.lock +++ b/uv.lock @@ -319,7 +319,6 @@ docs = [ { name = "mkdocs-macros-plugin" }, { name = "mkdocs-material" }, { name = "mkdocs-mermaid2-plugin" }, - { name = "mkdocs-section-index" }, { name = "mkdocstrings" }, { name = "mkdocstrings-python" }, { name = "pymdown-extensions" }, @@ -371,7 +370,6 @@ requires-dist = [ { name = "mkdocs-macros-plugin", marker = "extra == 'docs'", specifier = ">=1.3.7,<2.0.0" }, { name = "mkdocs-material", marker = "extra == 'docs'", specifier = ">=9.6.12,<10.0.0" }, { name = "mkdocs-mermaid2-plugin", marker = "extra == 'docs'", specifier = ">=1.2.1,<2.0.0" }, - { name = "mkdocs-section-index", marker = "extra == 'docs'", specifier = "==0.3.9" }, { name = "mkdocstrings", marker = "extra == 'docs'", specifier = "==0.26.1" }, { name = "mkdocstrings-python", marker = "extra == 'docs'", specifier = "==1.11.1" }, { name = "mypy", marker = "extra == 'typing'", specifier = "==1.2.0" }, @@ -1107,18 +1105,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/24/ce/c8a41cb0f3044990c8afbdc20c853845a9e940995d4e0cffecafbb5e927b/mkdocs_mermaid2_plugin-1.2.1-py3-none-any.whl", hash = "sha256:22d2cf2c6867d4959a5e0903da2dde78d74581fc0b107b791bc4c7ceb9ce9741", size = 17260 }, ] -[[package]] -name = "mkdocs-section-index" -version = "0.3.9" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "mkdocs" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/86/09/3cfcfec56740fba157991cd098c76dd08ef9c211db292c7c7d820d16c351/mkdocs_section_index-0.3.9.tar.gz", hash = "sha256:b66128d19108beceb08b226ee1ba0981840d14baf8a652b6c59e650f3f92e4f8", size = 13941 } -wheels = [ - { url = "https://files.pythonhosted.org/packages/d2/19/16f6368f69949ea2d0086197a86beda4d4f27f09bb8c59130922f03d335d/mkdocs_section_index-0.3.9-py3-none-any.whl", hash = "sha256:5e5eb288e8d7984d36c11ead5533f376fdf23498f44e903929d72845b24dfe34", size = 8728 }, -] - [[package]] name = "mkdocstrings" version = "0.26.1"