Avoid "no backward incompatible interface" term which uses a double
negation and replaces it with easier "backward compatible interface"
contruct.
(cherry picked from commit 179eb623d7)
* Use an rst table instead of a raw html table
* Rst is easier to read so we want to use it wherever possible
* Fix the jinja2 filters which create links so that they do not include
extraneous whitespace in the URL
* Normalize description data before sending them to the templates
* Render elements in module doc and sanity test for suboptions
* Add support to render module elements value in ansible-doc output
module html
* Add validate-module sanity test of sunoptions.
* Add current validate module failures to ignore list
* Fix CI failure
* fix rebase conflict
* Fix CI issues
* Fix review comments
* Add validate-modules failure in ignore list
* Docs: Show parameter types (in purple)
* Changes based on feedback
* Remove leftover statement after review
* Simplify TOC and support section
* Add missing 'v' to version_added
* Remove the v for version
* Update docs/templates/plugin.rst.j2
Co-Authored-By: dagwieers <dag@wieers.com>
* Update docs/templates/plugin.rst.j2
Co-Authored-By: dagwieers <dag@wieers.com>
* Move Author into Support section
* Avoid more "isn't included in any toctree" errors
* Add Red Hat support section, list module status
* Docs: Add a separate "seealso" section to the module docs
to list related modules and/or related references. This clears up the notes
section for things that are actual notes.
So you can add a section in your module documentation and four types of
references are possible.
seealso:
# Reference by module name
- module: aci_tenant
# Reference by module name, including description
- module: aci_tenant
description: ACI module to create tenants on a Cisco ACI fabric.
# Reference by rST documentation anchor
- ref: aci_guide
description: Detailed information on how to manage your ACI infrastructure using Ansible.
# Reference by Internet resource
- name: APIC Management Information Model reference
description: Complete reference of the APIC object model.
link: https://developer.cisco.com/docs/apic-mim-ref/
This PR also includes:
- Implements ansible-doc support
- Implements schema support for the seealso options
- Updates to the development documentation
- Rename filter convert_symbols_to_format to rst_ify, cfr the existing html_ify and tty_ify filters
- This makes the existing template a lot easier to read and fixes the confusion I had myself rereading the template (again).
- We fixed the possible suboption types (which was limited to 'bool' only)
* Use latest stable instead of devel docs
This commit: fa5c0282a4 relied upon
features present in Jinja-2.10 and above. The changes here allow us to
build the *rst* with older versions of jinja2.
While the HTML produced is perfectly valid, without the `trim` filter,
a lot of warnings are emitted (700 lines of warnings out of 2812 are
eliminated by this change)
Address Firefox table-rendering issues in docs. Refactor to use colspan to provide table cells which can vary in width and indentation; the outermost has the greatest colspan, and each nested key has a colspan of one less than the parent, with padding cells for indentation.
Apply styling to table cells to get the table height to work without hacks or browser-specific
styling. Simplify the markup and CSS by removing extra divs. Use two passes over the options, return values, and return facts in the Jinja2 module-docs template: one to determine the maximum nesting depth to compute the maximum colspan needed, plus one to lay out the rows.
* Treat C(...) as inline literal (as opposed to interpreted text).
* Making test for true and false more precise, to avoid matching 1, 1.0, etc.
* The 'is sameas' test already takes care of definedness.
* Update the documentation to list Python 3 as official
* Add some reference targets for inventory variables so we can link to docs
* Add a platform FAQ section
Populate it with
* virtualenv info (previously on the python3 support page)
* BSD (Link to the working with BSD page)
* Solaris (Document how to work around the non-POSIX shell on some
Solaris hosts)
Fixes#21594
* Fix some refs in the release_and_maintenance document
* Fix unindent error in module template
Fix for the module/plugin template unintentionally unindented inside of
a raw block, leading to errors like:
ERROR: docs/docsite/rst/modules/redshift_facts_module.rst:289:0: Explicit markup ends without a blank line; unexpected unindent.
* Make wording for Solaris troubleshooting better.
* centralize doc/config plugin lists
also update list for generation in docsite
added note to ensure they are in sync
* updated shell page to list plugins
added some more docs hinting at plugins being configurable
* fix edit link for plugins
The :ref: syntax is for linking to targets which are defined for the
whole document tree. `link`_ is for linking to targets which are inside
of the document. We want the latter for deprecated sections because
otherwise we'd have to create namespaced link targets for them.
Also fix expansion of version a deprecated module will be removed in
This PR includes:
- A fix for multiple-choice defaults
- A fix for messed up dictionary samples
- Cleaner defaults when they don't appear part of choices
* Improve default values and choices in module docs
So currently we show defaults and choices in separate columns.
For each parameter we have
- Mostly empty default and choices cells
- A list of choices and a separate default value
- Only a default value
So there's a lot of space being wasted on empty cells.
We can do this better.
* Improve Parameters section
* Add Choices back into column header
* Ensure the tables spans the complete page width
* Improve module docs return values
Currently the 5 columns shown doesn't make optimal use of the screen
estate, especially for facts modules this is a problem.
* Add returned facts as a separate section
* Remove whitespace and add support section
Since Notes were moved higher up, the Author, Status and Maintainer
information was now placed under the Return Values section.
* Switch Last Updated and Copyright
* Automatically stuff reference in commit message
So we probably want to track which edits were performed through the
Github interface, and this change automatically adds a label to the
commit message.
```yaml
<!--- Your description here -->
+label: docsite_pr
```
Eventually this allows to (on regular basis) list the changes from
documentation readers and process them in a separate process.
So I am still not satisfied with how required parameters are being
displayed (before it was yes/no, then it became required/optional, and
only required).
Now it will display in small green 'required' under the parameter name.
This is more convenient, and provides more room for the description.
Especially on smaller screens.
So people reading the module documentation usually look for parameters
first, and are interested in examples. However the notes are at the very
end even below the Return Values (the least interesting part).
So this change moves the notes higher up, below parameters, but before
examples so people at least see the notes.
This PR includes:
- Indentation of Jinja constructs
- Put parameter name in bold
- Title-case table headers
- Show 'required' when parameter is required (not yes/no)
- Left-align all values
This PR includes:
- An improvement to the parameter listing, where instead of yes/no, it
is indicated with required/optional (easier when scrolling through a
long list of parameters)
- Ensure that module reference, eg. M(foobar) do not include the module
document title
This PR includes:
- A fix to untemplated {{ plugin_type }} in docs
- Remove the additional info on how to edit module docs (see #36667)
- Add missing delimiter
Jordan Borean