docs(MARKDOWN,SPHINX): overhaul docs

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # PIB CLI Development Guide
 
-A development environment CLI, complete with tooling.
+A batteries included [make](https://www.gnu.org/software/make/) style CLI for [python](https://python.org) projects in [git](https://git-scm.com/) repositories.
 
 [Project Documentation](https://pib_cli.readthedocs.io/en/latest/)
 
@@ -24,3 +24,13 @@ Start the environment container:
 Spawn a shell inside the container:
 
 - `./container`
+
+## Environment Variables in the Dev Environment
+
+Developing `pib_cli` is a bit of a chicken and egg problem, as the project makes use of itself during development.
+
+To manage this, the `default config` is activated during the execution of tests, linting, etc.  You can see this [here](./assets/cli.yml).
+
+## Deviations from PEP
+
+I prefer to use a two-space indent, and so [yapf](https://github.com/google/yapf) is configured this way.  Please use the `dev fmt` command to match style on commits.

assets/Dockerfile

@@ -70,6 +70,7 @@ RUN apt-get update                      && \
     golang-github-pelletier-go-toml=1.8.*  \
     jq=1.6*                                \
     openssh-client=1:8.*                   \
+    pandoc=2.*                             \
     shellcheck=0.7.*                       \
     sudo=1.9.*                             \
     tig=2.5.*                              \

assets/cli.yml

@@ -28,6 +28,7 @@ cli_definition:
     commands:
       - '[ ! -d build/gettext ] || rm -rf build/gettext'
       - '[ ! -d "./source/codebase/${PIB_PROJECT_NAME}/${PIB_PROJECT_NAME}/_autosummary" ] || rm -rf "./source/codebase/${PIB_PROJECT_NAME}/${PIB_PROJECT_NAME}/_autosummary"'
+      - pandoc ../README.md --from markdown --to rst --columns=100 -s -o source/project/introduction.rst
       - |
         env PIB_CONFIG_FILE_LOCATION="$(pwd)/../pib_cli/config/default_cli_config.yml" sh -c "
           make gettext &&

assets/config_drift.diff

@@ -6,7 +6,7 @@
 < metadata:
 <   project_name: "pib_cli"
 <   documentation_root: "documentation"
-7,38d3
+7,39d3
 <   - name: "babel-extract"
 <     description: "Create an updated template file for translations."
 <     path: "repo_root"
@@ -31,6 +31,7 @@
 <     commands:
 <       - '[ ! -d build/gettext ] || rm -rf build/gettext'
 <       - '[ ! -d "./source/codebase/${PIB_PROJECT_NAME}/${PIB_PROJECT_NAME}/_autosummary" ] || rm -rf "./source/codebase/${PIB_PROJECT_NAME}/${PIB_PROJECT_NAME}/_autosummary"'
+<       - pandoc ../README.md --from markdown --to rst --columns=100 -s -o source/project/introduction.rst
 <       - |
 <         env PIB_CONFIG_FILE_LOCATION="$(pwd)/../pib_cli/config/default_cli_config.yml" sh -c "
 <           make gettext &&
@@ -39,16 +40,16 @@
 <         "
 <     success: "Documentation Built"
 <     failure: "Error Building Documentation"
-50c15
+51c15
 <       - env PIB_CONFIG_FILE_LOCATION="$(pwd)/../pib_cli/config/default_cli_config.yml" sh -c 'pytest --cov-report term-missing --cov-report html --cov-fail-under=100 --cov="${PIB_PROJECT_NAME}" "${PIB_PROJECT_NAME}/" ${PIB_OVERLOAD_ARGUMENTS}'
 ---
 >       - 'pytest --cov-report term-missing --cov-report html --cov-fail-under=100 --cov="${PIB_PROJECT_NAME}" "${PIB_PROJECT_NAME}/" ${PIB_OVERLOAD_ARGUMENTS}'
-56d20
+57d20
 <     container_only: true
-58,59d21
+59,60d21
 <       - './scripts/utilities/aspell_sort.sh'
 <       - 'tomll pyproject.toml'
-64,71d25
+65,72d25
 <   - name: "leaks"
 <     description: "Run a scan for leaked credentials in commits."
 <     container_only: true
@@ -57,33 +58,33 @@
 <       - 'gitleaks detect -v'
 <     success: "Credential leaks Test Passed!"
 <     failure: "Credential leaks Test Failed!"
-73d26
+74d26
 <     description: "Run the code linters."
-74a28
+75a28
 >     description: "Run the code linters."
-76,80d29
+77,81d29
 <       - 'shellcheck ${PIB_PROJECT_NAME}/bash/* -x'
 <       - 'shellcheck ${PIB_PROJECT_NAME}/container_init.sh'
 <       - 'darglint "${PIB_PROJECT_NAME}"'
 <       - 'pydocstyle "${PIB_PROJECT_NAME}"'
 <       - 'pydocstyle --config=.pydocstyle.tests "${PIB_PROJECT_NAME}"'
-91c40
+92c40
 <       - "poetry install -E pib_docs"
 ---
 >       - "poetry install"
-98c47
+99c47
 <       - 'bandit -r "${PIB_PROJECT_NAME}" -c pyproject.toml -x tests'
 ---
 >       - 'bandit -r "${PIB_PROJECT_NAME}" -x tests'
-100c49
+101c49
 <       - 'poetry export --without-hashes -f requirements.txt | safety check --stdin -i 41002'
 ---
 >       - 'poetry export --without-hashes -f requirements.txt | safety check --stdin'
-107c56
+108c56
 <       - env PIB_CONFIG_FILE_LOCATION="$(pwd)/../pib_cli/config/default_cli_config.yml" sh -c 'pytest ${PIB_OVERLOAD_ARGUMENTS}'
 ---
 >       - 'pytest ${PIB_OVERLOAD_ARGUMENTS}'
-110,116d58
+111,117d58
 <   - name: "types"
 <     description: "Run the type checker."
 <     path: "repo_root"

documentation/source/_static/markdown.css

@@ -0,0 +1,3 @@
+table.align-default.docutils {
+    margin-left: 0 !important;
+}

documentation/source/cli/user_guide.rst → documentation/source/cli/cli_reference.rst

@@ -1,10 +1,20 @@
-PIB CLI User Guide
-==================
+CLI Reference
+=============
+
+There are two categories of `pib_cli` commands:
+
+- internal commands
+- customizable commands
+
+While the internal commands are statically defined, you have complete control over the customizable commands.
+
+`pib_cli` ships with some default customized commands that you can use with your project right away.
+
 
 PIB CLI Internal Commands
 -------------------------
 
-This commands allow you to introspect the pib_cli application itself:
+These commands allow you to interact with the `pib_cli` application itself:
 
 .. click:: pib_cli.cli.interface.builtins:builtin_commands
     :prog: dev @pib
@@ -13,7 +23,7 @@ This commands allow you to introspect the pib_cli application itself:
 PIB CLI Default Custom Commands
 -------------------------------
 
-These are the default configuration based commands shipped with pib_cli:
+These are the default configuration based commands shipped with `pib_cli`:
 
 .. click:: pib_cli.cli.interface.custom:document_custom_commands
     :prog: dev

documentation/source/conf.py

@@ -18,9 +18,9 @@
 
 # -- Project information -----------------------------------------------------
 project = 'pib_cli'
-copyright = '2020, Niall Byrne'
+copyright = '2022, Niall Byrne'
 author = 'Niall Byrne'
-os.environ['PROJECT_NAME'] = project
+os.environ['PIB_PROJECT_NAME'] = project
 locale_dirs = ['locale/']
 
 # -- General configuration ---------------------------------------------------
@@ -36,6 +36,7 @@
     'sphinx_click.ext',
     'sphinx_autopackagesummary',
     'sphinx-jsonschema',
+    'sphinx_rtd_theme',
 ]
 
 source_suffix = {
@@ -74,12 +75,10 @@ def detect_tests():
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'haiku'
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
-html_theme_options = {
-    'body_max_width': '100%'
-}
+html_css_files = ['markdown.css']

documentation/source/index.rst

@@ -1,15 +1,18 @@
-PIB CLI's documentation
-=============================================
+pib_cli
+=======
+
+A development environment CLI, with a customizable YAML config.
 
 .. toctree::
    :maxdepth: 6
    :caption: Contents:
 .. toctree::
-   :glob:
 
-   cli/*
-   codebase/*
-   project/*
+   project/introduction.rst
+   cli/cli_reference.rst
+   codebase/codebase.rst
+   project/license.rst
+   project/repository.rst
 
 
 Indices and tables