From a1c216c31accb5b1e72e1416c55122425263eaee Mon Sep 17 00:00:00 2001 From: Kyle Finley Date: Wed, 14 Aug 2024 10:48:55 -0400 Subject: [PATCH 1/4] update doc dependencies, use `furo` theme --- .github/workflows/cicd.yml | 10 +- .github/workflows/on-push-pyinstaller.yml | 6 +- .github/workflows/release.yml | 12 +- docs/source/_static/css/custom.css | 8 - docs/source/_static/scripts/custom.js | 4 + docs/source/cdk/advanced_features.rst | 3 - docs/source/cdk/configuration.rst | 2 - docs/source/cdk/directory_structure.rst | 3 - docs/source/cfngin/blueprints.rst | 9 +- docs/source/cfngin/configuration.rst | 25 +- docs/source/cfngin/directory_structure.rst | 2 - .../cfngin/hooks/awslambda.PythonFunction.rst | 4 - .../cfngin/hooks/awslambda.PythonLayer.rst | 4 - docs/source/cfngin/hooks/index.rst | 3 - docs/source/cfngin/migrating.rst | 3 +- docs/source/cfngin/persistent_graph.rst | 8 +- docs/source/cfngin/remote_sources.rst | 3 - docs/source/cfngin/templates.rst | 6 +- docs/source/conf.py | 141 ++++---- docs/source/defining_tests.rst | 3 - docs/source/getting_started.rst | 10 +- docs/source/installation.rst | 20 +- docs/source/kubernetes/advanced_features.rst | 6 +- docs/source/kubernetes/configuration.rst | 2 - docs/source/kubernetes/examples.rst | 2 - docs/source/lookups/index.rst | 3 - docs/source/maintainers/release_process.rst | 2 - docs/source/maintainers/secrets.rst | 2 +- docs/source/python_setup.rst | 2 +- docs/source/quickstart/cloudformation.rst | 6 +- docs/source/quickstart/conduit.rst | 14 +- docs/source/quickstart/other_ways_to_use.rst | 2 - .../source/quickstart/private_static_site.rst | 2 - docs/source/repo_structure.rst | 2 - docs/source/runway_config.rst | 4 +- docs/source/serverless/advanced_features.rst | 2 - docs/source/serverless/configuration.rst | 4 +- .../source/serverless/directory_structure.rst | 3 - docs/source/staticsite/advanced_features.rst | 3 +- docs/source/staticsite/configuration.rst | 3 - .../source/staticsite/directory_structure.rst | 3 - docs/source/staticsite/examples.rst | 3 - docs/source/terminology.rst | 160 +++------ docs/source/terraform/advanced_features.rst | 3 - docs/source/terraform/configuration.rst | 2 - docs/source/upgrades.rst | 5 +- poetry.lock | 315 ++++++++++++------ pyproject.toml | 18 +- 48 files changed, 425 insertions(+), 437 deletions(-) delete mode 100644 docs/source/_static/css/custom.css create mode 100644 docs/source/_static/scripts/custom.js diff --git a/.github/workflows/cicd.yml b/.github/workflows/cicd.yml index d1a53bd4a..4d9df3373 100644 --- a/.github/workflows/cicd.yml +++ b/.github/workflows/cicd.yml @@ -90,7 +90,7 @@ jobs: - name: ๐Ÿ— Setup Python uses: finleyfamily/action-setup-python@v1.0.0 with: - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] - name: ๐Ÿ— Configure AWS Credentials uses: aws-actions/configure-aws-credentials@v4 with: @@ -126,7 +126,7 @@ jobs: - name: ๐Ÿ— Setup Python uses: finleyfamily/action-setup-python@v1.0.0 with: - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] python-version: ${{ matrix.python-version }} - name: โคต๏ธ Install Node Dependencies run: make npm-ci @@ -167,7 +167,7 @@ jobs: - name: ๐Ÿ— Setup Python uses: finleyfamily/action-setup-python@v1.0.0 with: - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] python-version: '3.10' - name: โคต๏ธ Install Ubuntu Dependencies run: | @@ -206,7 +206,7 @@ jobs: - name: ๐Ÿ— Setup Python uses: finleyfamily/action-setup-python@v1.0.0 with: - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] python-version: ${{ matrix.python-version }} - name: โคต๏ธ Install Node Dependencies run: make npm-install @@ -239,7 +239,7 @@ jobs: uses: finleyfamily/action-setup-python@v1.0.0 with: poetry-install: false - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] # Remove apt repos that are known to break from time to time # See https://github.com/actions/virtual-environments/issues/323 - name: Remove broken apt repos (ubuntu) diff --git a/.github/workflows/on-push-pyinstaller.yml b/.github/workflows/on-push-pyinstaller.yml index e2a26bfa2..48485ae7c 100644 --- a/.github/workflows/on-push-pyinstaller.yml +++ b/.github/workflows/on-push-pyinstaller.yml @@ -39,7 +39,7 @@ jobs: uses: finleyfamily/action-setup-python@v1.0.0 with: poetry-install: false - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] python-version: ${{ matrix.python-version }} # Remove apt repos that are known to break from time to time # See https://github.com/actions/virtual-environments/issues/323 @@ -81,7 +81,7 @@ jobs: uses: finleyfamily/action-setup-python@v1.0.0 with: poetry-install: false - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] python-version: ${{ matrix.python-version }} # Remove apt repos that are known to break from time to time # See https://github.com/actions/virtual-environments/issues/323 @@ -130,7 +130,7 @@ jobs: uses: finleyfamily/action-setup-python@v1.0.0 with: poetry-install: false - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] python-version: ${{ matrix.python-version }} - name: ๐Ÿ— Setup Node uses: actions/setup-node@v4 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 23349b58c..171e5252b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -32,7 +32,7 @@ jobs: - name: ๐Ÿ— Setup Python uses: finleyfamily/action-setup-python@v1.0.0 with: - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] python-version: ${{ matrix.python-version }} # Remove apt repos that are known to break from time to time # See https://github.com/actions/virtual-environments/issues/323 @@ -74,7 +74,7 @@ jobs: - name: ๐Ÿ— Setup Python uses: finleyfamily/action-setup-python@v1.0.0 with: - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] python-version: ${{ matrix.python-version }} # Remove apt repos that are known to break from time to time # See https://github.com/actions/virtual-environments/issues/323 @@ -116,7 +116,7 @@ jobs: - name: ๐Ÿ— Setup Python uses: finleyfamily/action-setup-python@v1.0.0 with: - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] python-version: ${{ matrix.python-version }} - name: ๐Ÿ— Setup Node uses: actions/setup-node@v4 @@ -204,7 +204,7 @@ jobs: - name: ๐Ÿ— Setup Python uses: finleyfamily/action-setup-python@v1.0.0 with: - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] # Remove apt repos that are known to break from time to time # See https://github.com/actions/virtual-environments/issues/323 - name: Remove broken apt repos (ubuntu) @@ -238,7 +238,7 @@ jobs: uses: finleyfamily/action-setup-python@v1.0.0 with: poetry-install: false - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] - name: ๐Ÿš€ Publish Distribution ๐Ÿ“ฆ to PyPI env: POETRY_PYPI_TOKEN_PYPI: ${{ secrets.pypi_password }} @@ -294,7 +294,7 @@ jobs: - name: ๐Ÿ— Setup Python uses: finleyfamily/action-setup-python@v1.0.0 with: - poetry-plugins: poetry-dynamic-versioning + poetry-plugins: poetry-dynamic-versioning[plugin] - name: ๐Ÿ— Configure AWS Credentials uses: aws-actions/configure-aws-credentials@v4 with: diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css deleted file mode 100644 index 5a2987518..000000000 --- a/docs/source/_static/css/custom.css +++ /dev/null @@ -1,8 +0,0 @@ -/* Change code blocks font and bump up font size slightly (normally 12px)*/ -.rst-content code.literal, -.rst-content pre.literal-block, -.rst-content div[class^="highlight"] pre, -.rst-content .linenodiv pre { - font-family: 'Inconsolata', monospace !important; - font-size: 14px !important; -} diff --git a/docs/source/_static/scripts/custom.js b/docs/source/_static/scripts/custom.js new file mode 100644 index 000000000..ae7a68475 --- /dev/null +++ b/docs/source/_static/scripts/custom.js @@ -0,0 +1,4 @@ +// open external links in new tabs +$(document).ready(function () { + $('a.external').attr('target', '_blank'); +}); diff --git a/docs/source/cdk/advanced_features.rst b/docs/source/cdk/advanced_features.rst index 1e60a9152..446f68227 100644 --- a/docs/source/cdk/advanced_features.rst +++ b/docs/source/cdk/advanced_features.rst @@ -7,9 +7,6 @@ Advanced Features Advanced features and detailed information for using CDK with Runway. -.. contents:: - :depth: 4 - .. _cdk.Build Steps: diff --git a/docs/source/cdk/configuration.rst b/docs/source/cdk/configuration.rst index fbea75639..5f4801cec 100644 --- a/docs/source/cdk/configuration.rst +++ b/docs/source/cdk/configuration.rst @@ -6,8 +6,6 @@ Configuration Standard `CDK `__ rules apply but, we have some added prerequisites, recommendations, and caveats. -.. contents:: - :depth: 4 ************* diff --git a/docs/source/cdk/directory_structure.rst b/docs/source/cdk/directory_structure.rst index 792b8aa06..743dd85a2 100644 --- a/docs/source/cdk/directory_structure.rst +++ b/docs/source/cdk/directory_structure.rst @@ -7,9 +7,6 @@ Directory Structure Example directory structures for a CDK module. -.. contents:: - :depth: 4 - ********** C# Example diff --git a/docs/source/cfngin/blueprints.rst b/docs/source/cfngin/blueprints.rst index 1e6b480df..ca31475e3 100644 --- a/docs/source/cfngin/blueprints.rst +++ b/docs/source/cfngin/blueprints.rst @@ -9,7 +9,7 @@ Blueprints ########## A |Blueprint| is a python classes that dynamically builds CloudFormation templates. -Where you would specify a raw Cloudformation template in a |stack| using the |template_path| key, you instead specify a |Blueprint| subclass using the |class_path| key. +Where you would specify a raw Cloudformation template in a |Stack| using the |template_path| key, you instead specify a |Blueprint| subclass using the |class_path| key. Traditionally Blueprints are built using troposphere_, but that is not absolutely necessary. @@ -28,9 +28,6 @@ In the end, all that is required is that the |Blueprint| is a subclass of :class """ -.. contents:: - :depth: 4 - ********* Variables @@ -81,7 +78,7 @@ TroposphereType =============== The :class:`~runway.cfngin.blueprints.variables.types.TroposphereType` can be used to generate resources for use in the :class:`~runway.cfngin.blueprints.base.Blueprint` directly from user-specified configuration. -Which of the below case applies depends on what ``defined_type`` was chosen, and how it would be normally used in the :ref:`Blueprint ` (and CloudFormation in general). +Which of the below case applies depends on what ``defined_type`` was chosen, and how it would be normally used in the :term:`Blueprint` (and :link:`CloudFormation` in general). Resource Types -------------- @@ -306,7 +303,7 @@ To use this in your |Blueprint|, you can get the name from context using ``self. Referencing the Stack short name ================================ -The |Stack| short name is the name you specified for the |stack| within your YAML config. +The |Stack| short name is the name you specified for the |Stack| within your YAML config. It does not include the |namespace|. If your CFNgin namespace is ``CFNginIsCool`` and the stack's short name is ``myAwesomeEC2Instance``, the short name would be ``myAwesomeEC2Instance``. diff --git a/docs/source/cfngin/configuration.rst b/docs/source/cfngin/configuration.rst index 0c1791a3d..e55d8b86a 100644 --- a/docs/source/cfngin/configuration.rst +++ b/docs/source/cfngin/configuration.rst @@ -15,9 +15,6 @@ In addition to the :ref:`Runway Config File `, there are two file It has been replaced with an internal CloudFormation engin (CFNgin). -.. contents:: - :depth: 4 - ********** runway.yml @@ -48,10 +45,10 @@ CloudFormation modules do not have any module-specific options. Parameters ========== -Runway can pass :ref:`Parameters ` to a CloudFormation module in place of or in addition to values in an :ref:`environment file `. -When :ref:`Parameters ` are passed to the module, the data type is retained (e.g. ``array``, ``boolean``, ``mapping``). +Runway can pass :term:`Parameters` to a CloudFormation module in place of or in addition to values in an :ref:`environment file `. +When :term:`Parameters` are passed to the module, the data type is retained (e.g. ``array``, ``boolean``, ``mapping``). -A typical usage pattern would be to use :ref:`Runway Lookups ` in combination with :ref:`Parameters ` to pass :ref:`deploy environment ` and/or region specific values to the module from the :ref:`Runway Config File `. +A typical usage pattern would be to use :ref:`Runway Lookups ` in combination with :term:`Parameters` to pass :term:`Deploy Environment` and/or region specific values to the module from the :ref:`Runway Config File `. .. rubric:: Example .. code-block:: yaml @@ -68,7 +65,7 @@ A typical usage pattern would be to use :ref:`Runway Lookups ` in combi Common Parameters ----------------- -Runway automatically makes the following commonly used :ref:`Parameters ` available to CloudFormation modules. +Runway automatically makes the following commonly used :term:`Parameters` available to CloudFormation modules. .. note:: If these parameters are already being explicitly defined in :attr:`deployment.parameters`/:attr:`module.parameters` the value provided will be used instead of what would be automatically added. @@ -77,7 +74,7 @@ Runway automatically makes the following commonly used :ref:`Parameters `. + Taken from the ``DEPLOY_ENVIRONMENT`` environment variable. This will the be current :term:`Deploy Environment`. .. data:: region :type: str @@ -259,7 +256,7 @@ Top-Level Fields In addition, this value can be used to create an S3 bucket that will be used to upload and store all CloudFormation templates. See :attr:`~cfngin.config.cfngin_bucket` for more detailed information. - In general, this is paired with the concept of :ref:`deploy environments ` to create a namespace per environment. + In general, this is paired with the concept of :term:`Deploy Environments ` to create a namespace per environment. .. rubric:: Example .. code-block:: yaml @@ -816,8 +813,8 @@ Using Outputs as Variables --------------------------- Since CFNgin encourages the breaking up of your CloudFormation stacks into entirely separate stacks, sometimes you'll need to pass values from one stack to another. -The way this is handled in CFNgin is by having one stack provide :ref:`Outputs ` for all the values that another stack may need, and then using those as the inputs for another stack's :attr:`~cfngin.stack.variables`. -CFNgin makes this easier for you by providing a syntax for :attr:`~cfngin.stack.variables` that will cause CFNgin to automatically look up the values of :ref:`Outputs ` from another stack in its config. +The way this is handled in CFNgin is by having one stack provide :term:`Outputs ` for all the values that another stack may need, and then using those as the inputs for another stack's :attr:`~cfngin.stack.variables`. +CFNgin makes this easier for you by providing a syntax for :attr:`~cfngin.stack.variables` that will cause CFNgin to automatically look up the values of :term:`Outputs ` from another stack in its config. To do so, use the :ref:`output lookup` in the :attr:`~cfngin.stack.variables` on the target stack. @@ -886,16 +883,16 @@ A pretty common use case is to have separate environments that you want to look For example, you might want a **production** and a **staging** environment. The production environment likely needs more instances, and often those instances will be of a larger instance type. -The parameters defined in an environment file, :attr:`deployment.parameters`, and/or :attr:`module.parameters` allow you to use your existing CFNgin config, but provide different values based on the current :ref:`deploy environment `. +The parameters defined in an environment file, :attr:`deployment.parameters`, and/or :attr:`module.parameters` allow you to use your existing CFNgin config, but provide different values based on the current :term:`Deploy Environment`. .. rubric:: Example .. code-block:: yaml vpcID: vpc-12345678 -Provided the key-value pair above, you will now be able to use this in your configs for a :ref:`deploy environment `. +Provided the key-value pair above, you will now be able to use this in your configs for a :term:`Deploy Environment`. They act as keys that can be used in your config file, providing a sort of templating ability. -This allows you to change the values of your config based on the current :ref:`deploy environment `. +This allows you to change the values of your config based on the current :term:`Deploy Environment`. For example, if you have a **webserver** stack, and you need to provide it a variable for the instance size it should use, you would have something like this in your config file. diff --git a/docs/source/cfngin/directory_structure.rst b/docs/source/cfngin/directory_structure.rst index 32acb0428..640c20910 100644 --- a/docs/source/cfngin/directory_structure.rst +++ b/docs/source/cfngin/directory_structure.rst @@ -6,8 +6,6 @@ Directory Structure Example directory structures for a CloudFormation module. -.. contents:: - :depth: 4 ********** diff --git a/docs/source/cfngin/hooks/awslambda.PythonFunction.rst b/docs/source/cfngin/hooks/awslambda.PythonFunction.rst index 28beb18d2..700a59c81 100644 --- a/docs/source/cfngin/hooks/awslambda.PythonFunction.rst +++ b/docs/source/cfngin/hooks/awslambda.PythonFunction.rst @@ -24,10 +24,6 @@ It also ensures that binary files built during the install process are compatibl .. versionadded:: 2.5.0 -.. contents:: Table of Contents - :local: - - **** Args diff --git a/docs/source/cfngin/hooks/awslambda.PythonLayer.rst b/docs/source/cfngin/hooks/awslambda.PythonLayer.rst index 2f4ad99ea..b3ab86e31 100644 --- a/docs/source/cfngin/hooks/awslambda.PythonLayer.rst +++ b/docs/source/cfngin/hooks/awslambda.PythonLayer.rst @@ -22,10 +22,6 @@ It also ensures that binary files built during the install process are compatibl .. versionadded:: 2.5.0 -.. contents:: Table of Contents - :local: - - **** Args diff --git a/docs/source/cfngin/hooks/index.rst b/docs/source/cfngin/hooks/index.rst index 8f2b36c3d..e7f51e0f5 100644 --- a/docs/source/cfngin/hooks/index.rst +++ b/docs/source/cfngin/hooks/index.rst @@ -84,9 +84,6 @@ Only the following actions allow pre/post hooks: Whether to stop execution if the hook fails. -.. contents:: - :depth: 4 - ---- diff --git a/docs/source/cfngin/migrating.rst b/docs/source/cfngin/migrating.rst index 7bfdbfe87..17bbd1617 100644 --- a/docs/source/cfngin/migrating.rst +++ b/docs/source/cfngin/migrating.rst @@ -4,8 +4,7 @@ Migrating from Stacker ###################### -.. contents:: - :depth: 4 + ********** Blueprints diff --git a/docs/source/cfngin/persistent_graph.rst b/docs/source/cfngin/persistent_graph.rst index 51a392d5c..102943709 100644 --- a/docs/source/cfngin/persistent_graph.rst +++ b/docs/source/cfngin/persistent_graph.rst @@ -4,11 +4,11 @@ Persistent Graph ################ -Each time Runway's CFNgin is run, it creates a dependency :ref:`graph ` of :class:`stacks `. +Each time Runway's CFNgin is run, it creates a dependency :term:`graph` of :class:`stacks `. This is used to determine the order in which to execute them. -This :ref:`graph ` can be persisted between runs to track the removal of :class:`stacks ` from the config file. +This :term:`graph` can be persisted between runs to track the removal of :class:`stacks ` from the config file. -When a |stack| is present in the persistent graph but not in the :ref:`graph ` constructed from the config file, CFNgin will delete the Stack from CloudFormation. +When a |Stack| is present in the persistent graph but not in the :term:`graph` constructed from the config file, CFNgin will delete the Stack from CloudFormation. This takes effect when running either the :ref:`deploy command ` or :ref:`destroy command `. To enable persistent graph, define the :attr:`~cfngin.config.persistent_graph_key` field as a unique value that will be used to construct the path to the persistent graph object in S3. @@ -36,7 +36,7 @@ The lock is a tag applied to the object at the start of one of these actions. The tag-key is **cfngin_lock_code** and the tag-value is UUID generated each time a config is processed. To lock a persistent graph object, the tag must not be present on the object. -For CFNgin to act on the :ref:`graph ` (modify or unlock) the value of the tag must match the UUID of the current CFNgin session. +For CFNgin to act on the :term:`graph` (modify or unlock) the value of the tag must match the UUID of the current CFNgin session. If the object is locked or the code does not match, an error will be raised and no action will be taken. This prevents two parties from acting on the same persistent graph object concurrently which would create a race condition. diff --git a/docs/source/cfngin/remote_sources.rst b/docs/source/cfngin/remote_sources.rst index 681eaa27c..071ffb293 100644 --- a/docs/source/cfngin/remote_sources.rst +++ b/docs/source/cfngin/remote_sources.rst @@ -59,9 +59,6 @@ By defining these additional sources you are able to extend your *$PATH* to make ... -.. contents:: - :depth: 4 - ************** Git Repository diff --git a/docs/source/cfngin/templates.rst b/docs/source/cfngin/templates.rst index 0ff3fe439..f4d0c593a 100644 --- a/docs/source/cfngin/templates.rst +++ b/docs/source/cfngin/templates.rst @@ -2,18 +2,16 @@ Templates ######### -CloudFormation templates can be provided via :ref:`Blueprints ` or JSON/YAML. +CloudFormation templates can be provided via :term:`Blueprints ` or JSON/YAML. JSON/YAML templates are specified for :class:`stacks ` via the :attr:`~cfngin.stack.template_path` config. -.. contents:: - :depth: 4 ***************** Jinja2 Templating ***************** -Templates with a ``.j2`` extension will be parsed using `Jinja2 `__. +Templates with a ``.j2`` extension will be parsed using :link:`Jinja2 `. The CFNgin ``context`` and ``mappings`` objects and stack ``variables`` objects are available for use in the template: .. code-block:: yaml diff --git a/docs/source/conf.py b/docs/source/conf.py index db5fe2eb3..1e9da9925 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -6,6 +6,7 @@ import os import sys +from datetime import date from pathlib import Path if sys.version_info < (3, 11): @@ -24,7 +25,7 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = PYPROJECT_TOML["tool"]["poetry"]["name"].title() -copyright = "2021, Onica Group" # noqa: A001 +copyright = f"{date.today().year}, Onica Group" # noqa: A001 author = PYPROJECT_TOML["tool"]["poetry"]["authors"][0] release = PYPROJECT_TOML["tool"]["poetry"]["version"] version = ".".join(release.split(".")[:2]) # short X.Y version @@ -37,62 +38,29 @@ default_role = None exclude_patterns = [] extensions = [ + "notfound.extension", "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", "sphinx.ext.intersphinx", "sphinx.ext.napoleon", "sphinx.ext.viewcode", + "sphinx_copybutton", + "sphinx_design", "sphinx_github_changelog", - "sphinx_tabs.tabs", "sphinxcontrib.apidoc", + "sphinxcontrib.external_links", + "sphinxcontrib.jquery", "sphinxcontrib.programoutput", ] highlight_language = "default" -intersphinx_mapping = { - "docker": ( - "https://docker-py.readthedocs.io/en/stable/", - None, - ), # link to docker docs - "python": ("https://docs.python.org/3", None), # link to python docs -} -language = None +language = "en" master_doc = "index" needs_extensions = {} -needs_sphinx = "3.5" +needs_sphinx = "7.4" nitpicky = False # TODO (kyle): enable nitpicky primary_domain = "py" -pygments_style = "material" # syntax highlighting style -# Appended to the end of each rendered file -rst_epilog = """ -.. |Blueprint| replace:: - :class:`~runway.cfngin.blueprints.base.Blueprint` - -.. |Dict| replace:: - :class:`~typing.Dict` - -.. |Protocol| replace:: - :class:`~typing.Protocol` - -.. |Stack| replace:: - :class:`~runway.cfngin.stack.Stack` - -.. |cfngin_bucket| replace:: - :attr:`~cfngin.config.cfngin_bucket` - -.. |class_path| replace:: - :attr:`~cfngin.stack.class_path` - -.. |namespace| replace:: - :attr:`~cfngin.config.namespace` - -.. |stack| replace:: - :class:`~cfngin.stack` - -.. |template_path| replace:: - :attr:`~cfngin.stack.template_path` - -""" -rst_prolog = "" - +pygments_style = "one-dark" # syntax highlighting style +pygments_dark_style = "one-dark" # syntax highlighting style source_suffix = {".rst": "restructuredtext"} templates_path = ["_templates"] # template dir relative to this dir @@ -100,25 +68,29 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_codeblock_linenos_style = "inline" -html_css_files = ["css/custom.css"] # files relative to html_static_path +html_css_files = [] # files relative to html_static_path html_favicon = None html_logo = None -html_theme = "sphinx_rtd_theme" # theme to use for HTML and HTML Help pages +html_theme = "furo" # theme to use for HTML and HTML Help pages html_theme_options = { - "navigation_depth": -1, # unlimited depth + "dark_css_variables": { + "font-stack--monospace": "Inconsolata, monospace", + "color-inline-code-background": "#24242d", + }, + "light_css_variables": { + "font-stack--monospace": "Inconsolata, monospace", + }, } html_short_title = f"{project} v{release}" html_title = f"{project} v{release}" -html_show_copyright = True -html_show_sphinx = True +html_show_copyright = False +html_show_sphinx = False html_static_path = ["_static"] # dir with static files relative to this dir - # -- Options for HTMLHelp output --------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-help-output htmlhelp_basename = "runwaydoc" - # -- Options for LaTeX output ------------------------------------------------ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output latex_documents = [ @@ -126,12 +98,10 @@ ] latex_elements = {} - # -- Options for manual page output ------------------------------------------ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-manual-page-output man_pages = [(master_doc, "runway", "runway Documentation", [author], 1)] - # -- Options for Texinfo output ---------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-texinfo-output texinfo_documents = [ @@ -146,7 +116,6 @@ ), ] - # -- Options for Epub output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output epub_exclude_files = ["search.html"] @@ -157,9 +126,12 @@ # https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html#environment os.environ["SPHINX_APIDOC_OPTIONS"] = "members" -# -- Options for sphinx-github-changelog ------------------------------------- -# GitHub PAT with "repo.public_repo" access provided by @ITProKyle -changelog_github_token = os.getenv("SPHINX_GITHUB_CHANGELOG_TOKEN", "") + +# -- Options of sphinx.ext.autosectionlabel ---------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html +autosectionlabel_maxdepth = 2 +autosectionlabel_prefix_document = True + # -- Options of sphinx.ext.autodoc ------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration @@ -167,10 +139,12 @@ autodoc_class_signature = "separated" autodoc_default_options = { "inherited-members": "dict", # show all inherited members - "member-order": "bysource", + "member-order": "alphabetical", "members": True, "show-inheritance": True, } +autodoc_inherit_docstrings = True +autodoc_member_order = "alphabetical" autodoc_type_aliases = { "CfnginContext": "runway.context.CfnginContext", "DirectoryPath": "Path", @@ -179,9 +153,23 @@ "RunwayContext": "runway.context.RunwayContext", } autodoc_typehints = "signature" +autodoc_typehints_format = "short" + + +# -- Options of sphinx.ext.intersphinx ------------------------------------------ +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html +intersphinx_mapping = { + "docker": ( + "https://docker-py.readthedocs.io/en/stable/", + None, + ), # link to docker docs + "packaging": ("https://packaging.pypa.io/en/stable/", None), + "python": ("https://docs.python.org/3", None), # link to python docs +} + -# -- Options for napoleon --------------------------------------------------- -# https://www.sphinx-doc.org/en/3.x/usage/extensions/napoleon.html#configuration +# -- Options for sphinx.ext.napoleon ---------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#configuration napoleon_attr_annotations = True napoleon_google_docstring = True napoleon_include_init_with_doc = False @@ -195,6 +183,20 @@ napoleon_use_param = False napoleon_use_rtype = True + +# -- Options for sphinx_copybutton --------------------------------- +# https://sphinx-copybutton.readthedocs.io/en/latest/index.html +copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " +copybutton_prompt_is_regexp = True +copybutton_remove_prompts = True +copybutton_line_continuation_character = "\\" + + +# -- Options for sphinx-github-changelog ------------------------------------- +# GitHub PAT with "repo.public_repo" access provided by @ITProKyle +changelog_github_token = os.getenv("SPHINX_GITHUB_CHANGELOG_TOKEN", "") + + # -- Options for sphinxcontrib.apidoc --------------------------------------- # https://github.com/sphinx-contrib/apidoc apidoc_excluded_paths = [ @@ -207,3 +209,22 @@ apidoc_output_dir = "apidocs" apidoc_separate_modules = True apidoc_toc_file = "index" + + +# -- Options for sphinxcontrib.external_links ------------------------------ +# https://sphinxcontribexternal-links.readthedocs.io/latest/configuration.html +external_links: dict[str, str] = { + "CloudFormation": "https://aws.amazon.com/cloudformation", + "troposphere": "https://github.com/cloudtools/troposphere", +} +external_links_substitutions: dict[str, str] = { + "Blueprint": ":class:`Blueprint `", + "Dict": ":class:`~typing.Dict`", + "dict": ":class:`~typing.Dict`", + "Protocol": ":class:`~typing.Protocol`", + "Stack": ":class:`~cfngin.stack`", + "cfngin_bucket": ":attr:`~cfngin.config.cfngin_bucket`", + "class_path": ":attr:`~cfngin.stack.class_path`", + "namespace": ":attr:`~cfngin.config.namespace`", + "template_path": ":attr:`~cfngin.stack.template_path`", +} diff --git a/docs/source/defining_tests.rst b/docs/source/defining_tests.rst index 34baf5fa8..b338f51f1 100644 --- a/docs/source/defining_tests.rst +++ b/docs/source/defining_tests.rst @@ -20,9 +20,6 @@ Tests are run in the order they are defined. - echo "Success!" -.. contents:: - :depth: 4 - ************* Test Failures diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 128eaf2e0..9be7d45f8 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -2,8 +2,6 @@ Getting Started Guide ##################### -.. contents:: - :depth: 4 ************** @@ -75,23 +73,23 @@ Deploying Your First Module that corresponds to your operating system. Then, change the downloaded file's permissions to allow execution. - .. tabs:: + .. tab-set:: - .. tab:: Linux + .. tab-item:: Linux .. code-block:: sh $ curl -L https://oni.ca/runway/latest/linux -o runway $ chmod +x runway - .. tab:: macOS + .. tab-item:: macOS .. code-block:: sh $ curl -L https://oni.ca/runway/latest/osx -o runway $ chmod +x runway - .. tab:: Windows + .. tab-item:: Windows .. code-block:: powershell diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 0372a4bb3..9173b6de4 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -28,21 +28,21 @@ on your operating system. | Windows | https://oni.ca/runway/latest/windows | +------------------+---------------------------------------------------+ -.. tabs:: +.. tab-set:: - .. tab:: Linux + .. tab-item:: Linux .. code-block:: sh curl -L https://oni.ca/runway/latest/linux -o runway - .. tab:: macOS + .. tab-item:: macOS .. code-block:: sh curl -L https://oni.ca/runway/latest/osx -o runway - .. tab:: Windows + .. tab-item:: Windows .. code-block:: powershell @@ -105,15 +105,15 @@ See `Why Version Lock Per-Project`_ for more info regarding this suggestion. **Suggested use:** Python projects -.. tabs:: +.. tab-set:: - .. tab:: poetry + .. tab-item:: poetry .. code-block:: sh poetry add runway - .. tab:: pip + .. tab-item:: pip .. code-block:: sh @@ -123,15 +123,15 @@ See `Why Version Lock Per-Project`_ for more info regarding this suggestion. .. rubric:: Usage -.. tabs:: +.. tab-set:: - .. tab:: poetry + .. tab-item:: poetry .. code-block:: sh poetry run runway --help - .. tab:: pip + .. tab-item:: pip .. code-block:: sh diff --git a/docs/source/kubernetes/advanced_features.rst b/docs/source/kubernetes/advanced_features.rst index 20e882dd0..1c8ce45e1 100644 --- a/docs/source/kubernetes/advanced_features.rst +++ b/docs/source/kubernetes/advanced_features.rst @@ -6,8 +6,6 @@ Advanced Features Advanced features and detailed information for using Kubernetes with Runway. -.. contents:: - :depth: 4 *************************** @@ -28,7 +26,7 @@ This can be set as a relative path or an absolute one. - ${env DEPLOY_ENVIRONMENT} - config -This would set `KUBECONFIG` to ``/.kube/$DEPLOY_ENVIRONMENT/config`` where ``$DEPLOY_ENVIRONMENT`` is the current Runway :ref:`deploy environment `. +This would set `KUBECONFIG` to ``/.kube/$DEPLOY_ENVIRONMENT/config`` where ``$DEPLOY_ENVIRONMENT`` is the current Runway :term:`Deploy Environment`. ---- @@ -50,7 +48,7 @@ Without a version specified, Runway will fallback to whatever ``kubectl`` it fin 1.14.5 -Lookups can be used to provide different versions for each :ref:`deploy environment `. +Lookups can be used to provide different versions for each :term:`Deploy Environment`. .. code-block:: yaml :caption: runway.yml diff --git a/docs/source/kubernetes/configuration.rst b/docs/source/kubernetes/configuration.rst index e5ba937eb..d092bab9d 100644 --- a/docs/source/kubernetes/configuration.rst +++ b/docs/source/kubernetes/configuration.rst @@ -6,8 +6,6 @@ Configuration Configuration options and parameters for :ref:`Kubernetes ` modules. -.. contents:: - :depth: 4 ******* diff --git a/docs/source/kubernetes/examples.rst b/docs/source/kubernetes/examples.rst index eb845250b..3f5e7d117 100644 --- a/docs/source/kubernetes/examples.rst +++ b/docs/source/kubernetes/examples.rst @@ -6,8 +6,6 @@ Examples Example uses of the :ref:`Kubernetes ` module -.. contents:: - :depth: 4 ****************** diff --git a/docs/source/lookups/index.rst b/docs/source/lookups/index.rst index c0e13c74a..ce120330c 100644 --- a/docs/source/lookups/index.rst +++ b/docs/source/lookups/index.rst @@ -47,9 +47,6 @@ For example, if i use ``${var region}`` in my Runway config file to resolve the Well, it can but it will resolve to the literal value provided, not an AWS region like you may expect. -.. contents:: - :depth: 4 - .. _lookup arguments: diff --git a/docs/source/maintainers/release_process.rst b/docs/source/maintainers/release_process.rst index c892eeae0..968c2b3d2 100644 --- a/docs/source/maintainers/release_process.rst +++ b/docs/source/maintainers/release_process.rst @@ -6,8 +6,6 @@ Release Process Steps that should be taken when preparing for and executing a release. -.. contents:: - :depth: 4 *********** diff --git a/docs/source/maintainers/secrets.rst b/docs/source/maintainers/secrets.rst index f80da5ca6..daaf8af80 100644 --- a/docs/source/maintainers/secrets.rst +++ b/docs/source/maintainers/secrets.rst @@ -55,7 +55,7 @@ Secrets specific to the repository, available to all environments. .. envvar:: TEST_PYPI_PASSWORD - Similar to :envvar:`PYPI_PASSWORD` but for https://test.pypi.org/. + Similar to :envvar:`PYPI_PASSWORD` but for :link:`Test PyPI`. .. envvar:: TEST_RUNNER_AWS_ACCESS_KEY_ID diff --git a/docs/source/python_setup.rst b/docs/source/python_setup.rst index 9acf1fc93..f759fab69 100644 --- a/docs/source/python_setup.rst +++ b/docs/source/python_setup.rst @@ -19,7 +19,7 @@ Perform the following to install/configure Python & package management tools. - Run ``source ~/.zshrc`` to use the updated PATH. - On Windows: - - Install `Python `_ (choose the latest ``Windows x86-64 executable installer`` and run it): + - Install :link:`Python` (choose the latest ``Windows x86-64 executable installer`` and run it): - On the initial setup page, click ``Customize installation`` - Leave all Optional Features selected, and click Next - On the Advanced Options page change the following options and click Install: diff --git a/docs/source/quickstart/cloudformation.rst b/docs/source/quickstart/cloudformation.rst index 6b0a90d3c..44a946bbc 100644 --- a/docs/source/quickstart/cloudformation.rst +++ b/docs/source/quickstart/cloudformation.rst @@ -19,9 +19,9 @@ CloudFormation Quickstart module`. + Optionally exclude the git branch name when determining the current :term:`Deploy Environment`. - This can be useful when using the directory name or environment variable to set the :ref:`deploy environment ` to ensure the correct value is used. + This can be useful when using the directory name or environment variable to set the :term:`Deploy Environment` to ensure the correct value is used. .. rubric:: Example .. code-block:: yaml diff --git a/docs/source/serverless/advanced_features.rst b/docs/source/serverless/advanced_features.rst index 6cae8571f..ba9cbc44f 100644 --- a/docs/source/serverless/advanced_features.rst +++ b/docs/source/serverless/advanced_features.rst @@ -6,8 +6,6 @@ Advanced Features Advanced features and detailed information for using Serverless Framework with Runway. -.. contents:: - :depth: 4 .. _sls-skip-npm-ci: diff --git a/docs/source/serverless/configuration.rst b/docs/source/serverless/configuration.rst index ea05ab32c..14d6840d1 100644 --- a/docs/source/serverless/configuration.rst +++ b/docs/source/serverless/configuration.rst @@ -6,8 +6,6 @@ Configuration Standard `Serverless Framework `__ rules apply but, we have some added prerequisites, recommendations, and caveats. -.. contents:: - :depth: 4 ************* @@ -104,7 +102,7 @@ Refer to the `Serverless Framework Documentation ` has a 1-to-1 mapping to Serverless's **stage**. +Runway's concept of a :term:`Deploy Environment` has a 1-to-1 mapping to Serverless's **stage**. For example, if the deploy environment is **dev**, Serverless will be run with ``--stage dev``. Each stage requires either its own variables file (even if empty for a particular stage) following a specific `File Naming`_ scheme and/or a configured ``environment`` for the module or deployment (see :ref:`Runway Config File ` for details). diff --git a/docs/source/serverless/directory_structure.rst b/docs/source/serverless/directory_structure.rst index e0a026f54..5130a9254 100644 --- a/docs/source/serverless/directory_structure.rst +++ b/docs/source/serverless/directory_structure.rst @@ -7,9 +7,6 @@ Directory Structure Example directory structures for a Serverless module. -.. contents:: - :depth: 4 - ************** Python Example diff --git a/docs/source/staticsite/advanced_features.rst b/docs/source/staticsite/advanced_features.rst index 99430a4a2..0125264d4 100644 --- a/docs/source/staticsite/advanced_features.rst +++ b/docs/source/staticsite/advanced_features.rst @@ -4,8 +4,7 @@ Advanced Features ################# -.. contents:: - :depth: 4 + .. _`Auth@Edge`: diff --git a/docs/source/staticsite/configuration.rst b/docs/source/staticsite/configuration.rst index cb156efd0..fe0cd0c95 100644 --- a/docs/source/staticsite/configuration.rst +++ b/docs/source/staticsite/configuration.rst @@ -9,9 +9,6 @@ Configuration options and parameters for :ref:`static site ` mod Example uses of the options and parameters can be found in the :ref:`Examples ` section. -.. contents:: - :depth: 4 - ******* Options diff --git a/docs/source/staticsite/directory_structure.rst b/docs/source/staticsite/directory_structure.rst index 5cec8cf7f..7bc03b60d 100644 --- a/docs/source/staticsite/directory_structure.rst +++ b/docs/source/staticsite/directory_structure.rst @@ -7,9 +7,6 @@ Directory Structure Example directory structures for a ref:`static site ` module. -.. contents:: - :depth: 4 - *********** Angular SPA diff --git a/docs/source/staticsite/examples.rst b/docs/source/staticsite/examples.rst index 185a47aa6..ffcb69266 100644 --- a/docs/source/staticsite/examples.rst +++ b/docs/source/staticsite/examples.rst @@ -7,9 +7,6 @@ Examples Example uses of the :ref:`static site ` module -.. contents:: - :depth: 4 - *********** Angular SPA diff --git a/docs/source/terminology.rst b/docs/source/terminology.rst index 9e190cfe7..ece07414b 100644 --- a/docs/source/terminology.rst +++ b/docs/source/terminology.rst @@ -1,132 +1,70 @@ -.. _blueprints: terminology.html#blueprint -.. _CloudFormation: https://aws.amazon.com/cloudformation/ -.. _CloudFormation Parameters: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html -.. _troposphere: https://github.com/cloudtools/troposphere - ########### Terminology ########### +.. glossary:: + Blueprint + A python class that is responsible for creating a :link:`CloudFormation` template using :link:`troposphere`. + :term:`Blueprints ` are deploying using :term:`CFNgin`. -****** -Runway -****** - -.. _term-deploy-env: - -Deploy Environment -================== - -Deploy environments are used for selecting the options/variables/parameters to be used with each Module_. -The deploy environment is derived from the current directory (if its not a git repo), active git branch, or environment variable (``DEPLOY_ENVIRONMENT``). -Standard deploy environments would be something like prod, dev, and test. - -When using a git branch, Runway expects the branch to be prefixed with **ENV-**. -If this is found, Runway knows that it should always use the value that follows the prefix. -If it's the **master** branch, Runway will use the deploy environment name of *common*. -If the branch name does not follow either of these schemas and Runway is being run interactively from the CLI, it will prompt of confirmation of the deploy environment that should be used. - -When using a directory, Runway expects the directory's name to be prefixed with **ENV-**. -If this is found, Runway knows that it should always use the value that follows the prefix. - - -Deployment -========== - -A :ref:`deployment` contains a list of `modules <#module>`_ and options for -all the modules_ in the deployment_. -A :ref:`runway-config` can contain multiple :ref:`deployments` and a deployment_ can contain multiple modules_. - - -Lookup (Runway) -=============== - -A method for expanding values in the :ref:`runway-config` file when processing a deployment/module. -These are only supported in select areas of the :ref:`runway-config` (see the config docs for more details). - - -Module -====== - -A :ref:`module` is a directory containing a single infrastructure-as-code tool configuration of an application, a component, or some infrastructure (eg. a set of `CloudFormation`_ templates). -It is defined in a `deployment`_ by path. -Modules can also contain granular options that only pertain to it based on its :attr:`module.type`. - - -.. _term-param: - -Parameters -========== - -A mapping of ``key: value`` that is passed to a module. -Through the use of a `Lookup (Runway)`_, the value can be changed per region or deploy environment. -The ``value`` can be any data type but, support for complex data types depends on the :attr:`module.type`. - - -------------------------------------------------------------------------------- - - -*************** -Runway's CFngin -*************** - - -.. _term-blueprint: - -Blueprint -========= - -A python class that is responsible for creating a CloudFormation template. -Usually this is built using troposphere_. - - -context -======= - -Context is responsible for translating the values passed in via the -command line and specified in the :class:`~cfngin.config` to :class:`stacks `. - + CFNgin + Runway's CloudFormation engine used to deploy :link:`CloudFormation` Templates (JSON or YAML) and :term:`Blueprints ` written using :link:`troposphere`. -.. _term-graph: + Deploy Environment + :term:`Deploy Environments ` are used for selecting the options/variables/parameters to be used with each :term:`Module`. + The :term:`Deploy Environment` is derived from the current directory (if its not a git repo), active git branch, or environment variable (``DEPLOY_ENVIRONMENT``). + Standard :term:`Deploy Environments ` would be something like prod, dev, and test. -graph -===== + When using a git branch, Runway expects the branch to be prefixed with **ENV-**. + If this is found, Runway knows that it should always use the value that follows the prefix. + If it's the **master** branch, Runway will use the :term:`Deploy Environment` name of *common*. + If the branch name does not follow either of these schemas and Runway is being run interactively from the CLI, it will prompt of confirmation of the :term:`Deploy Environment` that should be used. -A mapping of **object name** to **set/list of dependencies**. + When using a directory, Runway expects the directory's name to be prefixed with **ENV-**. + If this is found, Runway knows that it should always use the value that follows the prefix. -A graph is constructed for each execution of CFNgin from the contents of the -:class:`~cfngin.config` file. + Deployment + A :ref:`Deployment ` contains a list of :term:`Modules ` and options for all the :term:`Modules ` in the :term:`Deployment`. + A :ref:`runway-config` can contain multiple :ref:`deployments ` and a :term:`Deployment` can contain multiple :term:`Modules `. -.. rubric:: Example + Lookup + In the context of Runway, a :term:`Lookup` is a method for expanding values in the :ref:`runway-config` file when processing a :term:`Deployment`/:term:`Module`. + These are only supported in select areas of the :ref:`runway-config` (see the config docs for more details). -.. code-block:: json + In the context of :term:`CFNgin`, a :term:`Lookup` is method for expanding values in the :class:`~cfngin.config` at runtime. - { - "stack1": [], - "stack2": [ - "stack1" - ] - } + Module + A :ref:`Module ` is a directory containing a single Infrastructure-as-Code tool configuration of an application, a component, or some infrastructure (e.g. a set of :link:`CloudFormation` Templates). + It is defined in a :term:`Deployment` by path. + :term:`Modules ` can also contain granular options that only pertain to it based on its :attr:`module.type`. -- **stack1** depends on nothing. -- **stack2** depends on **stack1** + Output + A :link:`CloudFormation` Template concept. + :class:`Stacks ` can output values allowing easy access to those values. + Often used to export the unique ID's of resources that Templates create. + :term:`CFNgin` makes it easy to pull :term:`Outputs ` from one :class:`~cfngin.stack` and then use them in the :attr:`~cfngin.stack.variables` of another :class:`~cfngin.stack`. -lookup -====== + Parameters + A mapping of ``key: value`` that is passed to a :term:`Module`. + Through the use of a :term:`Lookup`, the value can be changed per region or :term:`Deploy Environment`. + The ``value`` can be any data type but, support for complex data types depends on the :attr:`module.type`. -A method for expanding values in the :class:`~cfngin.config` at runtime. By default -lookups are used to reference Output values from other :class:`stacks ` within the -same :attr:`~cfngin.config.namespace`. + graph + A mapping of **object name** to **set/list of dependencies**. + A graph is constructed for each execution of :term:`CFNgin` from the contents of a :class:`~cfngin.config` file. -.. _term-outputs: + .. rubric:: Example -output -====== + .. code-block:: json -A CloudFormation Template concept. -:class:`Stacks ` can output values, allowing easy access to those values. -Often used to export the unique ID's of resources that templates create. + { + "stack1": [], + "stack2": [ + "stack1" + ] + } -CFNgin makes it simple to pull outputs from one :class:`~cfngin.stack` and then use them in the :attr:`~cfngin.stack.variables` of another :class:`~cfngin.stack`. + - **stack1** depends on nothing. + - **stack2** depends on **stack1** diff --git a/docs/source/terraform/advanced_features.rst b/docs/source/terraform/advanced_features.rst index 31106ca83..6f7a558e9 100644 --- a/docs/source/terraform/advanced_features.rst +++ b/docs/source/terraform/advanced_features.rst @@ -7,9 +7,6 @@ Advanced Features Advanced features and detailed information for using Terraform with Runway. -.. contents:: - :depth: 4 - .. _tf-backend: diff --git a/docs/source/terraform/configuration.rst b/docs/source/terraform/configuration.rst index 97b265a64..78ad20f27 100644 --- a/docs/source/terraform/configuration.rst +++ b/docs/source/terraform/configuration.rst @@ -4,8 +4,6 @@ Configuration ############# -.. contents:: - :depth: 4 ******* diff --git a/docs/source/upgrades.rst b/docs/source/upgrades.rst index 2ad3aeb30..3cf989f9d 100644 --- a/docs/source/upgrades.rst +++ b/docs/source/upgrades.rst @@ -4,11 +4,10 @@ Upgrades ######## -.. contents:: - :depth: 4 - During a Runway upgrade (especially coming from a :code:`0.x` version) you may required to make changes to your configuration or modules. This page will describe common issues when upgrading and how to resolve them. + + ******************************* Updating the Runway Config File ******************************* diff --git a/poetry.lock b/poetry.lock index 5cc79abd2..7b68925c7 100644 --- a/poetry.lock +++ b/poetry.lock @@ -2,13 +2,13 @@ [[package]] name = "alabaster" -version = "0.7.13" -description = "A configurable sidebar-enabled Sphinx theme" +version = "0.7.16" +description = "A light, configurable Sphinx theme" optional = false -python-versions = ">=3.6" +python-versions = ">=3.9" files = [ - {file = "alabaster-0.7.13-py3-none-any.whl", hash = "sha256:1ee19aca801bbabb5ba3f5f258e4422dfa86f82f3e9cefb0859b283cdd7f62a3"}, - {file = "alabaster-0.7.13.tar.gz", hash = "sha256:a27a4a084d5e690e16e01e03ad2b2e552c61a65469419b907243193de1a84ae2"}, + {file = "alabaster-0.7.16-py3-none-any.whl", hash = "sha256:b46733c07dce03ae4e150330b975c75737fa60f0a7c591b6c8bf4928a28e2c92"}, + {file = "alabaster-0.7.16.tar.gz", hash = "sha256:75a8b99c28a5dad50dd7f8ccdd447a121ddb3892da9e53d1ca5cca3106d58d65"}, ] [[package]] @@ -86,6 +86,27 @@ files = [ [package.extras] dev = ["freezegun (>=1.0,<2.0)", "pytest (>=6.0)", "pytest-cov"] +[[package]] +name = "beautifulsoup4" +version = "4.12.3" +description = "Screen-scraping library" +optional = false +python-versions = ">=3.6.0" +files = [ + {file = "beautifulsoup4-4.12.3-py3-none-any.whl", hash = "sha256:b80878c9f40111313e55da8ba20bdba06d8fa3969fc68304167741bbf9e082ed"}, + {file = "beautifulsoup4-4.12.3.tar.gz", hash = "sha256:74e3d1928edc070d21748185c46e3fb33490f22f52a3addee9aee0f4f7781051"}, +] + +[package.dependencies] +soupsieve = ">1.2" + +[package.extras] +cchardet = ["cchardet"] +chardet = ["chardet"] +charset-normalizer = ["charset-normalizer"] +html5lib = ["html5lib"] +lxml = ["lxml"] + [[package]] name = "black" version = "24.8.0" @@ -1058,20 +1079,21 @@ files = [ [[package]] name = "doc8" -version = "0.11.2" +version = "1.1.1" description = "Style checker for Sphinx (or other) RST documentation" optional = false -python-versions = ">=3.6" +python-versions = ">=3.8" files = [ - {file = "doc8-0.11.2-py3-none-any.whl", hash = "sha256:9187da8c9f115254bbe34f74e2bbbdd3eaa1b9e92efd19ccac7461e347b5055c"}, - {file = "doc8-0.11.2.tar.gz", hash = "sha256:c35a231f88f15c204659154ed3d499fa4d402d7e63d41cba7b54cf5e646123ab"}, + {file = "doc8-1.1.1-py3-none-any.whl", hash = "sha256:e493aa3f36820197c49f407583521bb76a0fde4fffbcd0e092be946ff95931ac"}, + {file = "doc8-1.1.1.tar.gz", hash = "sha256:d97a93e8f5a2efc4713a0804657dedad83745cca4cd1d88de9186f77f9776004"}, ] [package.dependencies] -docutils = "*" +docutils = ">=0.19,<0.21" Pygments = "*" restructuredtext-lint = ">=0.7" stevedore = "*" +tomli = {version = "*", markers = "python_version < \"3.11\""} [[package]] name = "docker" @@ -1097,13 +1119,13 @@ websockets = ["websocket-client (>=1.3.0)"] [[package]] name = "docutils" -version = "0.17.1" +version = "0.20.1" description = "Docutils -- Python Documentation Utilities" optional = false -python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*" +python-versions = ">=3.7" files = [ - {file = "docutils-0.17.1-py2.py3-none-any.whl", hash = "sha256:cf316c8370a737a022b72b56874f6602acf974a37a9fba42ec2876387549fc61"}, - {file = "docutils-0.17.1.tar.gz", hash = "sha256:686577d2e4c32380bb50cbb22f575ed742d58168cee37e99117a854bcd88f125"}, + {file = "docutils-0.20.1-py3-none-any.whl", hash = "sha256:96f387a2c5562db4476f09f13bbab2192e764cac08ebbf3a34a95d9b1e4a59d6"}, + {file = "docutils-0.20.1.tar.gz", hash = "sha256:f08a4e276c3a1583a86dce3e34aba3fe04d02bba2dd51ed16106244e8a923e3b"}, ] [[package]] @@ -1162,6 +1184,23 @@ files = [ {file = "formic2-1.0.3.tar.gz", hash = "sha256:21bedd18fbd9010638b7449c7ce008b424a5f8835c224b81fbd07f666bfc6808"}, ] +[[package]] +name = "furo" +version = "2024.8.6" +description = "A clean customisable Sphinx documentation theme." +optional = false +python-versions = ">=3.8" +files = [ + {file = "furo-2024.8.6-py3-none-any.whl", hash = "sha256:6cd97c58b47813d3619e63e9081169880fbe331f0ca883c871ff1f3f11814f5c"}, + {file = "furo-2024.8.6.tar.gz", hash = "sha256:b63e4cee8abfc3136d3bc03a3d45a76a850bada4d6374d24c1716b0e01394a01"}, +] + +[package.dependencies] +beautifulsoup4 = "*" +pygments = ">=2.7" +sphinx = ">=6.0,<9.0" +sphinx-basic-ng = ">=1.0.0.beta2" + [[package]] name = "gitdb" version = "4.0.10" @@ -1417,17 +1456,17 @@ referencing = ">=0.31.0" [[package]] name = "jsx-lexer" -version = "1.0.0" +version = "2.0.1" description = "A JSX lexer for Pygments" optional = false python-versions = "*" files = [ - {file = "jsx-lexer-1.0.0.tar.gz", hash = "sha256:b5f5270cad47b065417fd7bdb780199d5166bd4a88a2a0fd7412e90e7a59b5cc"}, - {file = "jsx_lexer-1.0.0-py2.py3-none-any.whl", hash = "sha256:491783c7ae75f2cbde18f66c1362e93afd6e281078482215b70c1a8dfa61e57b"}, + {file = "jsx-lexer-2.0.1.tar.gz", hash = "sha256:0d9aa653e74d7973d74021dde8349896c0df094d8e40349b92b35e0930ed7f71"}, + {file = "jsx_lexer-2.0.1-py2.py3-none-any.whl", hash = "sha256:508a08757764356aa36fd703596fdd59f789104f44b6568c7a14e27e62e57ad4"}, ] [package.dependencies] -Pygments = ">=2.7" +Pygments = ">=2.12.0" [[package]] name = "junit-xml" @@ -2881,154 +2920,222 @@ files = [ {file = "snowballstemmer-2.2.0.tar.gz", hash = "sha256:09b16deb8547d3412ad7b590689584cd0fe25ec8db3be37788be3810cbf19cb1"}, ] +[[package]] +name = "soupsieve" +version = "2.6" +description = "A modern CSS selector implementation for Beautiful Soup." +optional = false +python-versions = ">=3.8" +files = [ + {file = "soupsieve-2.6-py3-none-any.whl", hash = "sha256:e72c4ff06e4fb6e4b5a9f0f55fe6e81514581fca1515028625d0f299c602ccc9"}, + {file = "soupsieve-2.6.tar.gz", hash = "sha256:e2e68417777af359ec65daac1057404a3c8a5455bb8abc36f1a9866ab1a51abb"}, +] + [[package]] name = "sphinx" -version = "4.5.0" +version = "7.4.7" description = "Python documentation generator" optional = false -python-versions = ">=3.6" +python-versions = ">=3.9" files = [ - {file = "Sphinx-4.5.0-py3-none-any.whl", hash = "sha256:ebf612653238bcc8f4359627a9b7ce44ede6fdd75d9d30f68255c7383d3a6226"}, - {file = "Sphinx-4.5.0.tar.gz", hash = "sha256:7bf8ca9637a4ee15af412d1a1d9689fec70523a68ca9bb9127c2f3eeb344e2e6"}, + {file = "sphinx-7.4.7-py3-none-any.whl", hash = "sha256:c2419e2135d11f1951cd994d6eb18a1835bd8fdd8429f9ca375dc1f3281bd239"}, + {file = "sphinx-7.4.7.tar.gz", hash = "sha256:242f92a7ea7e6c5b406fdc2615413890ba9f699114a9c09192d7dfead2ee9cfe"}, ] [package.dependencies] -alabaster = ">=0.7,<0.8" -babel = ">=1.3" -colorama = {version = ">=0.3.5", markers = "sys_platform == \"win32\""} -docutils = ">=0.14,<0.18" -imagesize = "*" -importlib-metadata = {version = ">=4.4", markers = "python_version < \"3.10\""} -Jinja2 = ">=2.3" -packaging = "*" -Pygments = ">=2.0" -requests = ">=2.5.0" -snowballstemmer = ">=1.1" +alabaster = ">=0.7.14,<0.8.0" +babel = ">=2.13" +colorama = {version = ">=0.4.6", markers = "sys_platform == \"win32\""} +docutils = ">=0.20,<0.22" +imagesize = ">=1.3" +importlib-metadata = {version = ">=6.0", markers = "python_version < \"3.10\""} +Jinja2 = ">=3.1" +packaging = ">=23.0" +Pygments = ">=2.17" +requests = ">=2.30.0" +snowballstemmer = ">=2.2" sphinxcontrib-applehelp = "*" sphinxcontrib-devhelp = "*" sphinxcontrib-htmlhelp = ">=2.0.0" sphinxcontrib-jsmath = "*" sphinxcontrib-qthelp = "*" -sphinxcontrib-serializinghtml = ">=1.1.5" +sphinxcontrib-serializinghtml = ">=1.1.9" +tomli = {version = ">=2", markers = "python_version < \"3.11\""} [package.extras] docs = ["sphinxcontrib-websupport"] -lint = ["docutils-stubs", "flake8 (>=3.5.0)", "isort", "mypy (>=0.931)", "types-requests", "types-typed-ast"] -test = ["cython", "html5lib", "pytest", "pytest-cov", "typed-ast"] +lint = ["flake8 (>=6.0)", "importlib-metadata (>=6.0)", "mypy (==1.10.1)", "pytest (>=6.0)", "ruff (==0.5.2)", "sphinx-lint (>=0.9)", "tomli (>=2)", "types-docutils (==0.21.0.20240711)", "types-requests (>=2.30.0)"] +test = ["cython (>=3.0)", "defusedxml (>=0.7.1)", "pytest (>=8.0)", "setuptools (>=70.0)", "typing_extensions (>=4.9)"] [[package]] -name = "sphinx-github-changelog" -version = "1.3.0" -description = "Build a sphinx changelog from GitHub Releases" +name = "sphinx-basic-ng" +version = "1.0.0b2" +description = "A modern skeleton for Sphinx themes." optional = false -python-versions = ">=3.8,<4.0" +python-versions = ">=3.7" files = [ - {file = "sphinx_github_changelog-1.3.0-py3-none-any.whl", hash = "sha256:eb5424d590ae7866e77b8db7eecf283678cba76b74d90b17bc4f3872976407eb"}, - {file = "sphinx_github_changelog-1.3.0.tar.gz", hash = "sha256:b898adc52131147305b9cb893c2a4cad0ba2912178ed8f88b62bf6f43a2baaa4"}, + {file = "sphinx_basic_ng-1.0.0b2-py3-none-any.whl", hash = "sha256:eb09aedbabfb650607e9b4b68c9d240b90b1e1be221d6ad71d61c52e29f7932b"}, + {file = "sphinx_basic_ng-1.0.0b2.tar.gz", hash = "sha256:9ec55a47c90c8c002b5960c57492ec3021f5193cb26cebc2dc4ea226848651c9"}, ] [package.dependencies] -docutils = "*" -requests = "*" -Sphinx = "*" +sphinx = ">=4.0" + +[package.extras] +docs = ["furo", "ipython", "myst-parser", "sphinx-copybutton", "sphinx-inline-tabs"] [[package]] -name = "sphinx-rtd-theme" -version = "1.3.0" -description = "Read the Docs theme for Sphinx" +name = "sphinx-copybutton" +version = "0.5.2" +description = "Add a copy button to each of your code cells." optional = false -python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7" +python-versions = ">=3.7" files = [ - {file = "sphinx_rtd_theme-1.3.0-py2.py3-none-any.whl", hash = "sha256:46ddef89cc2416a81ecfbeaceab1881948c014b1b6e4450b815311a89fb977b0"}, - {file = "sphinx_rtd_theme-1.3.0.tar.gz", hash = "sha256:590b030c7abb9cf038ec053b95e5380b5c70d61591eb0b552063fbe7c41f0931"}, + {file = "sphinx-copybutton-0.5.2.tar.gz", hash = "sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd"}, + {file = "sphinx_copybutton-0.5.2-py3-none-any.whl", hash = "sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e"}, ] [package.dependencies] -docutils = "<0.19" -sphinx = ">=1.6,<8" -sphinxcontrib-jquery = ">=4,<5" +sphinx = ">=1.8" [package.extras] -dev = ["bump2version", "sphinxcontrib-httpdomain", "transifex-client", "wheel"] +code-style = ["pre-commit (==2.12.1)"] +rtd = ["ipython", "myst-nb", "sphinx", "sphinx-book-theme", "sphinx-examples"] [[package]] -name = "sphinx-tabs" -version = "3.4.5" -description = "Tabbed views for Sphinx" +name = "sphinx-design" +version = "0.6.1" +description = "A sphinx extension for designing beautiful, view size responsive web components." optional = false -python-versions = "~=3.7" +python-versions = ">=3.9" files = [ - {file = "sphinx-tabs-3.4.5.tar.gz", hash = "sha256:ba9d0c1e3e37aaadd4b5678449eb08176770e0fc227e769b6ce747df3ceea531"}, - {file = "sphinx_tabs-3.4.5-py3-none-any.whl", hash = "sha256:92cc9473e2ecf1828ca3f6617d0efc0aa8acb06b08c56ba29d1413f2f0f6cf09"}, + {file = "sphinx_design-0.6.1-py3-none-any.whl", hash = "sha256:b11f37db1a802a183d61b159d9a202314d4d2fe29c163437001324fe2f19549c"}, + {file = "sphinx_design-0.6.1.tar.gz", hash = "sha256:b44eea3719386d04d765c1a8257caca2b3e6f8421d7b3a5e742c0fd45f84e632"}, +] + +[package.dependencies] +sphinx = ">=6,<9" + +[package.extras] +code-style = ["pre-commit (>=3,<4)"] +rtd = ["myst-parser (>=2,<4)"] +testing = ["defusedxml", "myst-parser (>=2,<4)", "pytest (>=8.3,<9.0)", "pytest-cov", "pytest-regressions"] +testing-no-myst = ["defusedxml", "pytest (>=8.3,<9.0)", "pytest-cov", "pytest-regressions"] +theme-furo = ["furo (>=2024.7.18,<2024.8.0)"] +theme-im = ["sphinx-immaterial (>=0.12.2,<0.13.0)"] +theme-pydata = ["pydata-sphinx-theme (>=0.15.2,<0.16.0)"] +theme-rtd = ["sphinx-rtd-theme (>=2.0,<3.0)"] +theme-sbt = ["sphinx-book-theme (>=1.1,<2.0)"] + +[[package]] +name = "sphinx-github-changelog" +version = "1.4.0" +description = "Build a sphinx changelog from GitHub Releases" +optional = false +python-versions = "<4.0,>=3.8" +files = [ + {file = "sphinx_github_changelog-1.4.0-py3-none-any.whl", hash = "sha256:cdf2099ea3e4587ae8637be7ba609738bfdeca4bd80c5df6fc45046735ae5c2f"}, + {file = "sphinx_github_changelog-1.4.0.tar.gz", hash = "sha256:204745e93a1f280e4664977b5fee526b0a011c92ca19c304bd01fd641ddb6393"}, ] [package.dependencies] docutils = "*" -pygments = "*" -sphinx = "*" +requests = "*" +Sphinx = "*" + +[[package]] +name = "sphinx-notfound-page" +version = "1.0.4" +description = "Sphinx extension to build a 404 page with absolute URLs" +optional = false +python-versions = ">=3.8" +files = [ + {file = "sphinx_notfound_page-1.0.4-py3-none-any.whl", hash = "sha256:f7c26ae0df3cf3d6f38f56b068762e6203d0ebb7e1c804de1059598d7dd8b9d8"}, + {file = "sphinx_notfound_page-1.0.4.tar.gz", hash = "sha256:2a52f49cd367b5c4e64072de1591cc367714098500abf4ecb9a3ecb4fec25aae"}, +] + +[package.dependencies] +sphinx = ">=5" [package.extras] -code-style = ["pre-commit (==2.13.0)"] -testing = ["bs4", "coverage", "pygments", "pytest (>=7.1,<8)", "pytest-cov", "pytest-regressions", "rinohtype"] +doc = ["sphinx-autoapi", "sphinx-rtd-theme", "sphinx-tabs", "sphinxemoji"] +test = ["tox"] [[package]] name = "sphinxcontrib-apidoc" -version = "0.3.0" +version = "0.5.0" description = "A Sphinx extension for running 'sphinx-apidoc' on each build" optional = false -python-versions = "*" +python-versions = ">=3.8" files = [ - {file = "sphinxcontrib-apidoc-0.3.0.tar.gz", hash = "sha256:729bf592cf7b7dd57c4c05794f732dc026127275d785c2a5494521fdde773fb9"}, - {file = "sphinxcontrib_apidoc-0.3.0-py2.py3-none-any.whl", hash = "sha256:6671a46b2c6c5b0dca3d8a147849d159065e50443df79614f921b42fbd15cb09"}, + {file = "sphinxcontrib-apidoc-0.5.0.tar.gz", hash = "sha256:65efcd92212a5f823715fb95ee098b458a6bb09a5ee617d9ed3dead97177cd55"}, + {file = "sphinxcontrib_apidoc-0.5.0-py3-none-any.whl", hash = "sha256:c671d644d6dc468be91b813dcddf74d87893bff74fe8f1b8b01b69408f0fb776"}, ] [package.dependencies] pbr = "*" -Sphinx = ">=1.6.0" +Sphinx = ">=5.0.0" [[package]] name = "sphinxcontrib-applehelp" -version = "1.0.4" +version = "2.0.0" description = "sphinxcontrib-applehelp is a Sphinx extension which outputs Apple help books" optional = false -python-versions = ">=3.8" +python-versions = ">=3.9" files = [ - {file = "sphinxcontrib-applehelp-1.0.4.tar.gz", hash = "sha256:828f867945bbe39817c210a1abfd1bc4895c8b73fcaade56d45357a348a07d7e"}, - {file = "sphinxcontrib_applehelp-1.0.4-py3-none-any.whl", hash = "sha256:29d341f67fb0f6f586b23ad80e072c8e6ad0b48417db2bde114a4c9746feb228"}, + {file = "sphinxcontrib_applehelp-2.0.0-py3-none-any.whl", hash = "sha256:4cd3f0ec4ac5dd9c17ec65e9ab272c9b867ea77425228e68ecf08d6b28ddbdb5"}, + {file = "sphinxcontrib_applehelp-2.0.0.tar.gz", hash = "sha256:2f29ef331735ce958efa4734873f084941970894c6090408b079c61b2e1c06d1"}, ] [package.extras] -lint = ["docutils-stubs", "flake8", "mypy"] +lint = ["mypy", "ruff (==0.5.5)", "types-docutils"] +standalone = ["Sphinx (>=5)"] test = ["pytest"] [[package]] name = "sphinxcontrib-devhelp" -version = "1.0.2" -description = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp document." +version = "2.0.0" +description = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp documents" optional = false -python-versions = ">=3.5" +python-versions = ">=3.9" files = [ - {file = "sphinxcontrib-devhelp-1.0.2.tar.gz", hash = "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"}, - {file = "sphinxcontrib_devhelp-1.0.2-py2.py3-none-any.whl", hash = "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e"}, + {file = "sphinxcontrib_devhelp-2.0.0-py3-none-any.whl", hash = "sha256:aefb8b83854e4b0998877524d1029fd3e6879210422ee3780459e28a1f03a8a2"}, + {file = "sphinxcontrib_devhelp-2.0.0.tar.gz", hash = "sha256:411f5d96d445d1d73bb5d52133377b4248ec79db5c793ce7dbe59e074b4dd1ad"}, ] [package.extras] -lint = ["docutils-stubs", "flake8", "mypy"] +lint = ["mypy", "ruff (==0.5.5)", "types-docutils"] +standalone = ["Sphinx (>=5)"] test = ["pytest"] +[[package]] +name = "sphinxcontrib-external-links" +version = "0.1.1" +description = "Sphinx extension for easily adding reusable external links." +optional = false +python-versions = "<4.0,>=3.9" +files = [ + {file = "sphinxcontrib_external_links-0.1.1-py3-none-any.whl", hash = "sha256:d2ec5572179fa004eeec7b5450d2c0bc3e52022c51871b684a7655069a223064"}, + {file = "sphinxcontrib_external_links-0.1.1.tar.gz", hash = "sha256:1b982e9fb960b2983e87ce64892f28cd0b4fa918560f8e63426641eb16558812"}, +] + +[package.dependencies] +sphinx = ">=7.2,<9" + [[package]] name = "sphinxcontrib-htmlhelp" -version = "2.0.1" +version = "2.1.0" description = "sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files" optional = false -python-versions = ">=3.8" +python-versions = ">=3.9" files = [ - {file = "sphinxcontrib-htmlhelp-2.0.1.tar.gz", hash = "sha256:0cbdd302815330058422b98a113195c9249825d681e18f11e8b1f78a2f11efff"}, - {file = "sphinxcontrib_htmlhelp-2.0.1-py3-none-any.whl", hash = "sha256:c38cb46dccf316c79de6e5515e1770414b797162b23cd3d06e67020e1d2a6903"}, + {file = "sphinxcontrib_htmlhelp-2.1.0-py3-none-any.whl", hash = "sha256:166759820b47002d22914d64a075ce08f4c46818e17cfc9470a9786b759b19f8"}, + {file = "sphinxcontrib_htmlhelp-2.1.0.tar.gz", hash = "sha256:c9e2916ace8aad64cc13a0d233ee22317f2b9025b9cf3295249fa985cc7082e9"}, ] [package.extras] -lint = ["docutils-stubs", "flake8", "mypy"] +lint = ["mypy", "ruff (==0.5.5)", "types-docutils"] +standalone = ["Sphinx (>=5)"] test = ["html5lib", "pytest"] [[package]] @@ -3075,43 +3182,45 @@ Sphinx = ">=1.7.0" [[package]] name = "sphinxcontrib-qthelp" -version = "1.0.3" -description = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp document." +version = "2.0.0" +description = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp documents" optional = false -python-versions = ">=3.5" +python-versions = ">=3.9" files = [ - {file = "sphinxcontrib-qthelp-1.0.3.tar.gz", hash = "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72"}, - {file = "sphinxcontrib_qthelp-1.0.3-py2.py3-none-any.whl", hash = "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"}, + {file = "sphinxcontrib_qthelp-2.0.0-py3-none-any.whl", hash = "sha256:b18a828cdba941ccd6ee8445dbe72ffa3ef8cbe7505d8cd1fa0d42d3f2d5f3eb"}, + {file = "sphinxcontrib_qthelp-2.0.0.tar.gz", hash = "sha256:4fe7d0ac8fc171045be623aba3e2a8f613f8682731f9153bb2e40ece16b9bbab"}, ] [package.extras] -lint = ["docutils-stubs", "flake8", "mypy"] -test = ["pytest"] +lint = ["mypy", "ruff (==0.5.5)", "types-docutils"] +standalone = ["Sphinx (>=5)"] +test = ["defusedxml (>=0.7.1)", "pytest"] [[package]] name = "sphinxcontrib-serializinghtml" -version = "1.1.5" -description = "sphinxcontrib-serializinghtml is a sphinx extension which outputs \"serialized\" HTML files (json and pickle)." +version = "2.0.0" +description = "sphinxcontrib-serializinghtml is a sphinx extension which outputs \"serialized\" HTML files (json and pickle)" optional = false -python-versions = ">=3.5" +python-versions = ">=3.9" files = [ - {file = "sphinxcontrib-serializinghtml-1.1.5.tar.gz", hash = "sha256:aa5f6de5dfdf809ef505c4895e51ef5c9eac17d0f287933eb49ec495280b6952"}, - {file = "sphinxcontrib_serializinghtml-1.1.5-py2.py3-none-any.whl", hash = "sha256:352a9a00ae864471d3a7ead8d7d79f5fc0b57e8b3f95e9867eb9eb28999b92fd"}, + {file = "sphinxcontrib_serializinghtml-2.0.0-py3-none-any.whl", hash = "sha256:6e2cb0eef194e10c27ec0023bfeb25badbbb5868244cf5bc5bdc04e4464bf331"}, + {file = "sphinxcontrib_serializinghtml-2.0.0.tar.gz", hash = "sha256:e9d912827f872c029017a53f0ef2180b327c3f7fd23c87229f7a8e8b70031d4d"}, ] [package.extras] -lint = ["docutils-stubs", "flake8", "mypy"] +lint = ["mypy", "ruff (==0.5.5)", "types-docutils"] +standalone = ["Sphinx (>=5)"] test = ["pytest"] [[package]] name = "stevedore" -version = "5.0.0" +version = "5.2.0" description = "Manage dynamic plugins for Python applications" optional = false python-versions = ">=3.8" files = [ - {file = "stevedore-5.0.0-py3-none-any.whl", hash = "sha256:bd5a71ff5e5e5f5ea983880e4a1dd1bb47f8feebbb3d95b592398e2f02194771"}, - {file = "stevedore-5.0.0.tar.gz", hash = "sha256:2c428d2338976279e8eb2196f7a94910960d9f7ba2f41f3988511e95ca447021"}, + {file = "stevedore-5.2.0-py3-none-any.whl", hash = "sha256:1c15d95766ca0569cad14cb6272d4d31dae66b011a929d7c18219c176ea1b5c9"}, + {file = "stevedore-5.2.0.tar.gz", hash = "sha256:46b93ca40e1114cea93d738a6c1e365396981bb6bb78c27045b7587c9473544d"}, ] [package.dependencies] @@ -3358,4 +3467,4 @@ test = ["big-O", "importlib-resources", "jaraco.functools", "jaraco.itertools", [metadata] lock-version = "2.0" python-versions = ">=3.9, <3.13" -content-hash = "aa980ba7d8eb1e6f5b619643581b077c649c13f70070caa2859de656e5421daa" +content-hash = "05c7023fe4de9e6457ebcd9422d6e6a735c4c4d181117f826424bb5878d84076" diff --git a/pyproject.toml b/pyproject.toml index e916f7b48..14e910cdb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -65,13 +65,17 @@ pre-commit = "^3.8.0" semver = "^2.13" # only used in .github/scripts/urlshortener [tool.poetry.group.docs.dependencies] -doc8 = ">=0.10" # for linting with vscode rst extension -jsx-lexer = "^1.0" -sphinx = "^4.3" -sphinx-github-changelog = "^1.1" -sphinx-rtd-theme = "^1.0" -sphinx-tabs = "^3.2" -sphinxcontrib-apidoc = "^0.3" +doc8 = "^1.1.1" +furo = "^2024.8.6" +jsx-lexer = "^2.0.1" +sphinx = "^7.4.7" +sphinx-copybutton = "^0.5.2" +sphinx-design = "^0.6.1" +sphinx-github-changelog = "^1.4.0" +sphinx-notfound-page = "^1.0.4" +sphinxcontrib-apidoc = "^0.5.0" +sphinxcontrib-external-links = "^0.1.1" +sphinxcontrib-jquery = "^4.1" sphinxcontrib-programoutput = "^0.17" [tool.poetry.group.lint.dependencies] From d25bf0ddb8fd35cfcfe266124a9244ae9519bac6 Mon Sep 17 00:00:00 2001 From: Kyle Finley Date: Wed, 14 Aug 2024 10:50:02 -0400 Subject: [PATCH 2/4] fix spelling --- .vscode/cspell.json | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/.vscode/cspell.json b/.vscode/cspell.json index e95577a5a..9eb419de4 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -105,6 +105,7 @@ "codecov", "configvars", "copydir", + "datetimez", "devel", "dockerized", "domparator", @@ -115,6 +116,7 @@ "ekscluster", "eksservicerole", "EOCD", + "errmsg", "excinfo", "execglobals", "Fakhreddine", @@ -128,6 +130,7 @@ "FQDNs", "frontmatter", "fstring", + "furo", "getgid", "getpreferredencoding", "getuid", @@ -139,6 +142,7 @@ "humanreadable", "identless", "igittigitt", + "Inconsolata", "indentless", "instancerole", "intersphinx", @@ -184,6 +188,7 @@ "prehook", "prepad", "prevdir", + "pyupgrade", "PYXMLSEC", "readacl", "refreshable", @@ -222,7 +227,10 @@ "tmpdirname", "tomap", "tomli", + "tomlsort", "topdown", + "troyready", + "tryceratops", "typehints", "typeshed", "unittests", @@ -230,12 +238,6 @@ "usefixtures", "viewcode", "writeacl", - "xmlsec", - "troyready", - "tomlsort", - "pyupgrade", - "tryceratops", - "errmsg", - "datetimez" + "xmlsec" ] } From 9ea2b18e380eafc0210ae1d307ab982be72bce8c Mon Sep 17 00:00:00 2001 From: Kyle Finley Date: Wed, 14 Aug 2024 11:06:13 -0400 Subject: [PATCH 3/4] enable poetry-dynamic-versioning for some reason, it got disabled --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 14e910cdb..d9dba4a65 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -176,7 +176,7 @@ omit = [ [tool.poetry-dynamic-versioning] # poetry self add "poetry-dynamic-versioning[plugin]" bump = true -enable = false +enable = true fix-shallow-repository = true metadata = false strict = true From 5b87182115cf04473e8ac034014c7de4c39421c4 Mon Sep 17 00:00:00 2001 From: Kyle Finley Date: Wed, 14 Aug 2024 11:15:05 -0400 Subject: [PATCH 4/4] install types group when building docs --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 62bbf124f..a179c419f 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -18,7 +18,7 @@ build: # https://python-poetry.org/docs/managing-dependencies/#dependency-groups # VIRTUAL_ENV needs to be set manually for now. # See https://github.com/readthedocs/readthedocs.org/pull/11152/ - - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs + - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs,types # Build documentation in the docs/ directory with Sphinx sphinx: