diff --git a/docs/_static/.create_dir b/docs/_static/.create_dir new file mode 100644 index 0000000..e69de29 diff --git a/docs/conf.py b/docs/conf.py index a757adf..ebbe7bd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -82,7 +82,6 @@ templates_path = ["_templates"] html_static_path = ["_static"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - ### theme ### # html_theme = "alabaster" diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index be8be23..0000000 --- a/docs/index.md +++ /dev/null @@ -1,92 +0,0 @@ -# octodns documentation - -```{include} ../README.md ---- -end-before: '## Table of Contents' ---- -``` - -______________________________________________________________________ - -## User documentation - -```{toctree} -:caption: Getting Started: -:maxdepth: 1 - -examples/README.md -examples/basic/README.md -examples/migrating-to-octodns/README.md -records.md -``` - -```{toctree} -:caption: Guides: -:maxdepth: 1 -:glob: - -[a-q]* -``` - -______________________________________________________________________ - -## Module documentation - -```{toctree} -:caption: Providers: -:maxdepth: 2 -:glob: - -modules/provider/* -``` - -```{toctree} -:caption: Sources: -:maxdepth: 2 -:glob: - -modules/source/* -``` - -```{toctree} -:caption: Records: -:maxdepth: 2 -:glob: - -modules/record/* -``` - -```{toctree} -:caption: Processors: -:maxdepth: 2 -:glob: - -modules/processor/* -``` - -```{toctree} -:caption: Other modules: -:titlesonly: -:glob: - -modules/* -modules/cmds/* -modules/secret/* -``` - -______________________________________________________________________ - -## Indices and tables - -- {ref}`genindex` -- {ref}`modindex` - - - -```{toctree} -:caption: Project info: -:titlesonly: - -info/changelog.md -info/license.md -``` diff --git a/docs/processors.md b/docs/processors.md deleted file mode 100644 index 70ee8f7..0000000 --- a/docs/processors.md +++ /dev/null @@ -1,59 +0,0 @@ -# octoDNS processors - -## Available processors - -These are listed in the main [`README`](../README.md#processors) - -## Configuring processors - -Configuring processors is done in the main config file. - -### Defining a processor configuration - -This is done under the top-level `processors` key in the octoDNS config file (for example `config.yaml`), as a sibling to the `manager` key. - -The `processors` key contains YAML objects, where the key is the name of the processor, and the `class` value within that object refers to the processor name. - -For example, to define a provider called `custom_meta` using the [`MetaProcessor`](../octodns/processor/meta.py) in order to extend the default `include_meta` behaviour: - -```yaml -manager: - include_meta: false # disable default, basic `meta` records -processors: - custom_meta: - class: octodns.processor.meta.MetaProcessor - record_name: meta - include_time: true - include_uuid: true - include_provider: true - include_version: false -``` - -**NOTE:** the specific parameters for each processor are only documented within [the code](../octodns/processor/) - -### Utilising the processor configuration - -#### On **individual** domains - -Each domain can utilise the processor independently by adding the name of the defined processor to a `processors` key beneath a `zone`: - -```yaml -zones: - example.com.: - source: - - yaml_config - target: - - hetzner - processors: - - custom_meta -``` - -#### On **all** domains - -To utilise the processor on **all** domains automatically, including new domains added to the `zones` config in future then you can add this to the `processors` key under the `manager` section of the configuration: - -```yaml -manager: - processors: - - custom_meta -``` diff --git a/docs/source/api/processor.rst b/docs/source/api/processor.rst new file mode 100644 index 0000000..60b5261 --- /dev/null +++ b/docs/source/api/processor.rst @@ -0,0 +1,87 @@ +Processor +========= + +Defining a processor configuration +---------------------------------- + +This is done under the top-level ``processors`` key in the octoDNS config file +(for example ``config.yaml``), as a sibling to the ``manager`` key. + +The ``processors`` key contains YAML objects, where the key is the name of the +processor, and the ``class`` value within that object refers to the processor +name. + +For example, to define a provider called ``custom_meta`` using the +:py:class:`octodns.processor.meta.MetaProcessor` in order to extend the default +``include_meta`` behaviour:: + + manager: + include_meta: false # disable default, basic `meta` records + processors: + custom_meta: + class: octodns.processor.meta.MetaProcessor + record_name: meta + include_time: true + include_uuid: true + include_provider: true + include_version: false + +Utilising the processor configuration +------------------------------------- + +On **individual** domains +......................... + +Each domain can utilise the processor independently by adding the name of the +defined processor to a ``processors`` key beneath a ``zone``:: + + zones: + example.com.: + source: + - yaml_config + target: + - hetzner + processors: + - custom_meta + +On **all** domains +.................. + +To utilise the processor on **all** domains automatically, including new +domains added to the ``zones`` config in future then you can add this to the +``processors`` key under the ``manager`` section of the configuration:: + + manager: + processors: + - custom_meta + + +.. autoclass:: octodns.processor.base.BaseProcessor + :inherited-members: + +.. automodule:: octodns.processor.acme + :inherited-members: + +.. automodule:: octodns.processor.arpa + :inherited-members: + +.. automodule:: octodns.processor.filter + :inherited-members: + +.. automodule:: octodns.processor.meta + :inherited-members: + +.. automodule:: octodns.processor.ownership + :inherited-members: + +.. automodule:: octodns.processor.restrict + :inherited-members: + +.. automodule:: octodns.processor.spf + :inherited-members: + +.. automodule:: octodns.processor.templating + :inherited-members: + +.. automodule:: octodns.processor.trailing_dots + :inherited-members: diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 1231adc..a02eda7 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -138,6 +138,8 @@ configured in YAML as follows:: ... strict_supports: true +.. _automatic-ptr-generation: + Automatic PTR generation ------------------------ diff --git a/docs/source/examples/README.rst b/docs/source/examples/README.rst index 0cfa735..949814c 100644 --- a/docs/source/examples/README.rst +++ b/docs/source/examples/README.rst @@ -15,6 +15,8 @@ of not letting perfect get in the way of good enough, or really existing at all. It's being uploaded as a starting point. PRs/suggestions welcome as are ideas for other subjects to cover. +.. _running-powerdns: + Running PowerDNS ---------------- diff --git a/docs/source/examples/basic/README.md b/docs/source/examples/basic/README.md index 1fb34f0..74e848d 100644 --- a/docs/source/examples/basic/README.md +++ b/docs/source/examples/basic/README.md @@ -27,7 +27,7 @@ $ source env/bin/activate (env) $ pip install -r requirements.txt ``` -Finally check out [Running PowerDNS](../README.md#running-powerdns) to get a local +Finally check out [Running PowerDNS](#running-powerdns) to get a local instance of PowerDNS up and going before continuing. ## Running octoDNS the first time diff --git a/docs/source/examples/migrating-to-octodns/README.md b/docs/source/examples/migrating-to-octodns/README.md index c542158..fb30bab 100644 --- a/docs/source/examples/migrating-to-octodns/README.md +++ b/docs/source/examples/migrating-to-octodns/README.md @@ -55,7 +55,7 @@ just to have something to work with the the actual process that begins in the next step. It's not something you'd normally do when migrating to octoDNS. Step 0 is to get a local PowerDNS instance running. -Check out out [Running PowerDNS](../README.rst#running-powerdns) for info on +Check out out [Running PowerDNS](#running-powerdns) for info on starting that up. Once you've done that run the following. You can ignore the output and move on to the next step. @@ -68,7 +68,7 @@ output and move on to the next step. Once you have your configuration files and octoDNS installed you're ready to dump your zone configs. Here we've assumed that the provider being used supports `list_zones`, not all do. If you get an error to that effect see -[dynamic-zone-config](/getting-started#dynamic-zone-config) for +[dynamic-zone-config](#dynamic-zone-config) for details on how to explicitly list your zones in the config file. We first tell octodns-dump where to find our config file. We then tell it that diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index e3c5dee..681e413 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -6,7 +6,7 @@ Workspace Running through the following commands will install the latest release of octoDNS and set up a place for your config files to live. To determine if -provider specific requirements are necessary see the :doc:`index#providers` +provider specific requirements are necessary see the :ref:`provider-list` below.:: $ mkdir dns @@ -41,6 +41,8 @@ separate accounts and each manage a distinct set of zones. A good example of this this might be ``./config/staging.yaml`` & ``./config/production.yaml``. We'll focus on a ``config/production.yaml``. +.. _dynamic-zone-config: + Dynamic Zone Config ................... diff --git a/docs/source/index.rst b/docs/source/index.rst index f72785f..51f0bbf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -33,6 +33,8 @@ Documentation examples/README.rst api.rst +.. _provider-list: + Providers --------- @@ -293,7 +295,7 @@ Processors * - `AcmeManagingProcessor`_ - Useful when processes external to octoDNS are managing acme challenge DNS records, e.g. LetsEncrypt * - `AutoArpa`_ - - See :doc:`configuration#automatic-ptr-generation` + - See :ref:`automatic-ptr-generation` * - `EnsureTrailingDots`_ - Processor that ensures ALIAS, CNAME, DNAME, MX, NS, PTR, and SRVs have trailing dots * - `ExcludeRootNsChanges`_