.. _docs-system-tooling-aliases:


######################################################################
Shell Aliases & Wrapper Scripts
######################################################################

A quick-reference inventory of the shell aliases, Bash functions, and
wrapper scripts that support the Documentation System workflow.
Aliases live in Brad's dotfiles repo
(``git@github.com:stancel/brads-bash-settings.git``, checked out at
``~/``). They are decomposed across several sourced files loaded by
``~/.bash_aliases``.


**********************************************************************
Source Files
**********************************************************************

.. _docs-system-tooling-aliases-source-files:

Aliases and functions are loaded in this order by ``~/.bash_aliases``:

1. ``~/.bash_main_vars`` --- environment variables (must be set first).
2. ``~/.bash_aliases_all`` --- OS-independent aliases (navigation,
   templates, publishing, docs-\* shortcuts).
3. ``~/.bash_aliases_machine_inventory`` --- SSH targets for servers.
4. ``~/.bash_aliases_ansible`` --- Ansible-specific options.
5. ``~/.bash_functions`` --- Bash functions and the
   ``add-publish-template-*`` aliases that call wrapper scripts.
6. ``~/.bash_aliases_ubuntu`` **or** ``~/.bash_aliases_mac`` ---
   OS-specific overrides loaded last.


**********************************************************************
Documentation Navigation (``docs-*``)
**********************************************************************

.. _docs-system-tooling-aliases-navigation:

Each alias ``cd``-s into the repo and opens the VS Code workspace.

Personal / Writings repos
======================================================================

.. _docs-system-tooling-aliases-navigation-personal:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Alias
     - Target path
   * - ``docs-doc-system``
     - ``~/Writings/Documentation_System``
   * - ``docs-linux``
     - ``~/Writings/Linux``
   * - ``docs-devops``
     - ``~/Writings/DevOps-Docs``
   * - ``docs-ai``
     - ``~/Writings/Artificial-Intelligence``
   * - ``docs-server-programs``
     - ``~/DevOps-Personal/Server_Programs``
   * - ``docs-accounting``
     - ``~/Writings/Accounting``
   * - ``docs-entrepreneurship``
     - ``~/Writings/Entrepreneurship``
   * - ``docs-home-network``
     - ``~/Writings/Home_Network``
   * - ``docs-investing``
     - ``~/Writings/Investing_and_Dividends``
   * - ``docs-radio``
     - ``~/Writings/Radio``
   * - ``docs-spy-and-infosec``
     - ``~/Writings/Spy-and-InfoSec``
   * - ``docs-systems-design``
     - ``~/Writings/Systems-Design``
   * - ``docs-all-writings``
     - ``~/Writings`` (parent directory)

OpsInsights repos
======================================================================

.. _docs-system-tooling-aliases-navigation-opsinsights:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Alias
     - Target path
   * - ``docs-ops-user``
     - ``~/Sites/opsinsights-user-documentation``
   * - ``docs-ops-clients``
     - ``~/Sites/opsinsights-clients-documentation``
   * - ``docs-ops-developer``
     - ``~/Sites/opsinsights-developer-onboarding-documentation``
   * - ``docs-ops-devops``
     - ``~/Sites/opsinsights-devops-documentation``
   * - ``docs-ops-processes``
     - ``~/Sites/opsinsights-process-documentation``
   * - ``docs-ops-sqlreportwriters``
     - ``~/Sites/opsinsights-sqlwriters-documentation``
   * - ``docs-ops-audit``
     - ``~/Sites/opsinsights-audit-documentation``
   * - ``docs-ops-secure-connection``
     - ``~/Sites/opsinsights-secure-connection-documentation``
   * - ``docs-black-knight-integration``
     - ``~/Sites/black-knight-processfast``


**********************************************************************
Template Editing (``templates-edit-*``)
**********************************************************************

.. _docs-system-tooling-aliases-template-editing:

Open a cookiecutter template in VS Code for editing. All templates
now live in the consolidated ``stancel/doc-templates`` repo at
``~/DevOps-Personal/Templates/``.

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Alias
     - Template
   * - ``templates-edit-add-server-program``
     - ``cookiecutter-add-brad-server-program``
   * - ``templates-edit-add-linux-section``
     - ``cookiecutter-add-linux-section``
   * - ``templates-edit-add-opsinsights-client-doc``
     - ``cookiecutter-add-opsinsights-client-doc``
   * - ``templates``
     - ``cd ~/DevOps-Personal/Templates`` (parent dir)

.. note::

   ``templates-edit-add-devops-section`` and
   ``templates-edit-add-ai-section`` do not exist yet. To add them,
   append to ``~/.bash_aliases_all``:

   .. code-block:: bash

      alias templates-edit-add-devops-section='cd ${HOME}/DevOps-Personal/Templates/cookiecutter-add-devops-section && code workspace.code-workspace'
      alias templates-edit-add-ai-section='cd ${HOME}/DevOps-Personal/Templates/cookiecutter-add-ai-section && code workspace.code-workspace'


**********************************************************************
Section Creation (``add-publish-template-*``)
**********************************************************************

.. _docs-system-tooling-aliases-section-creation:

Wrapper scripts that ``cd`` to the target repo and invoke
``cookiecutter`` with the correct local template. Defined in
``~/.bash_functions``.

.. list-table::
   :header-rows: 1
   :widths: 40 30 30

   * - Alias
     - Script
     - Target repo
   * - ``add-publish-template-server-program``
     - ``add-server-program.sh``
     - Server_Programs
   * - ``add-publish-template-linux-section``
     - ``add-linux-section.sh``
     - Linux
   * - ``add-publish-template-ops-client``
     - ``add-ops-client.sh``
     - OpsInsights clients

New wrapper scripts (created 2026-04-17, not yet aliased):

.. list-table::
   :header-rows: 1
   :widths: 30 30 40

   * - Script
     - Template
     - Target repo
   * - ``add-devops-section.sh``
     - ``cookiecutter-add-devops-section``
     - DevOps-Docs (``source/``)
   * - ``add-ai-section.sh``
     - ``cookiecutter-add-ai-section``
     - AI-Docs (``source/``)

To wire these into the alias system, append to ``~/.bash_functions``:

.. code-block:: bash

   alias add-publish-template-devops-section='${HOME}/.local/bin/add-devops-section.sh'
   alias add-publish-template-ai-section='${HOME}/.local/bin/add-ai-section.sh'


**********************************************************************
Publishing Shortcuts (``publish-*``)
**********************************************************************

.. _docs-system-tooling-aliases-publishing:

Build documentation into various output formats. Defined in
``~/.bash_aliases_all``.

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Alias
     - Command
   * - ``publish-sphinx-html``
     - ``make clean && make html``
   * - ``publish-sphinx-pdf``
     - ``make clean && make latexpdf``
   * - ``publish-docutils-pdf``
     - ``rst2pdf $1 $2``
   * - ``publish-docutils-epub2``
     - ``rst2epub2 $1 $2``
   * - ``publish-docutils-slides``
     - ``rst2html5slides $1 $2``
   * - ``publish-docutils-pptx``
     - ``rst2pptx $1 $2``
   * - ``publish-pandoc-pdf``
     - ``pandoc -f rst -t latex $1 -o $2``
   * - ``publish-options-code-blocks``
     - ``pygmentize -L lexers`` (lists available syntax-highlight lexers)


**********************************************************************
Documentation System Scripts (``docs-*``)
**********************************************************************

.. _docs-system-tooling-aliases-scripts:

Standalone scripts at ``~/.local/bin/``. These are **not** aliases ---
they are full Bash scripts called directly or via ``make`` targets.

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Script
     - Purpose
   * - ``docs-env.sh``
     - Per-repo pyenv virtualenv lifecycle (``create``, ``activate``,
       ``sync``, ``status``, ``list``). Called by ``make env``.
   * - ``docs-audit.sh``
     - Fleet-wide drift detector. Checks every registered repo against
       the version matrix, baseline files, and conf.py standards.
   * - ``docs-refresh.sh``
     - Restarts documentation containers and clears caches. Supports
       ``-t <hub>`` for targeting a specific hub.
   * - ``docs-add-project.sh``
     - Adds a project's docs to an aggregation hub. Interactive (``-i``)
       or command-line mode.
   * - ``docs-sync-webhooks.sh``
     - Webhook-related sync operations.
   * - ``manage-pyenv-virtualenvs.sh``
     - Low-level pyenv virtualenv install/remove. ``docs-env.sh``
       supersedes this for doc-system repos.


**********************************************************************
Cookiecutter Utility
**********************************************************************

.. _docs-system-tooling-aliases-cookiecutter:

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Alias
     - Command
   * - ``add-new-cookiecutter-template``
     - ``~/.local/bin/setup-new-template.sh $1`` --- scaffolds a new
       cookiecutter template directory.


**********************************************************************
Consolidated Template Repository
**********************************************************************

.. _docs-system-tooling-aliases-template-repo:

All cookiecutter templates for the Documentation System live in a
single Git repo:

- **GitHub:** ``stancel/doc-templates``
- **Local:** ``~/DevOps-Personal/Templates/``
- **Templates:**
  - ``cookiecutter-add-brad-server-program`` (Server_Programs)
  - ``cookiecutter-add-linux-section`` (Linux)
  - ``cookiecutter-add-devops-section`` (DevOps-Docs) --- new
  - ``cookiecutter-add-ai-section`` (AI-Docs) --- new
  - ``cookiecutter-add-opsinsights-client-doc`` (OpsInsights clients)

The former individual GitHub repos
(``stancel/cookiecutter-add-brad-server-program`` and
``stancel/cookiecutter-add-linux-section``) have been archived.
``ProcessFast/cookiecutter-add-opsinsights-client-doc`` remains
active on GitHub but the local workflow now uses the consolidated
repo's copy.