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
This is something I always wanted, a 'Edit on GitHub' button for module
documentation.
I also removed the additional statement in the footer with instructions
on how to edit the module documentation.
PS The links go directly into the GitHub file editor now !
* Docs refactor as outlined in https://github.com/ansible/proposals/issues/79. Moves content into 'guides'; refactors TOC; fixes CSS; design tweaks to layout and CSS; fixes generated plugin, CLI and module docs to fix links accodingly; more.
* Adding extra blank line for shippable
Enforce module deprecation.
After module has reached the end of it's deprecation cycle we will replace it with a docs stub.
* Replace deprecated modules with docs-only sub
* Use of deprecated past deprecation cycle gives meaningful message (see examples below)
* Enforce documentation.deprecation dict via `schema.py`
* Update `ansible-doc` and web docs to display documentation.deprecation
* Document that structure in `dev_guide`
* Ensure that all modules starting with `_` have a `deprecation:` block
* Ensure `deprecation:` block is only used on modules that start with `_`
* `removed_in` A string which represents when this module needs **deleting**
* CHANGELOG.md and porting_guide_2.5.rst list removed modules as well as alternatives
* CHANGELOG.md links to porting guide index
To ensure that meaningful messages are given to the user if they try to use a module at the end of it's deprecation cycle we enforce the module to contain:
```python
if __name__ == '__main__':
removed_module()
```
Comparing the old module docs, with the devel docs the
options/arguments/parameters are no longer sorted.
Also, both in the old module docs and the devel docs the result values
are not sorted where they probably should.
* Render nested return value documentation for more then one level
in the generated webdocs.
* Remove unnecessary code and cleanup
* Implement recursive option documentation
* Build elbow intendation style for options and return documentation
* (minor) fix broken link, awkward phrasing
Simple transposition error was resulting in a link not
being properly htmlified.
Also clean up redundant 'this' and trailing whitespace.
Signed-off-by: Ed Santiago <santiago@redhat.com>
* Edits
* fixed module generation
added missing lookup page
point to plugins when plugins
made modules singular
add display for verbose an debug messages
nicer templating, changed generation order for ref
corrected links
moved most of lookup docs to plugin section
* Copy edits
* Fixed typos
* Clarified wording
reason: The link is showing verbatim in the docs, where it should only
show "knowledge base article".
Also, generating the docs shows a lot of:
docs/docsite/rst/win_acl_module.rst:424: WARNING: Unknown target name: "know ledge base article<https://access.redhat.com/articles/rhel-top-support-policies>".
Generate rst docs for plugins
Based on rst generated for modules. But generated plugin
docs go into docs/docsite/rst/plugins/$PLUGIN_TYPE/plugin_name.rst
( docs/docsite/rst/plugins/connection/ssh.py for ex)
* move plugins docs to rst/*_plugins/ subdirs for namespace
* Only gen support pages for modules for now.
* Add generated plugin docs to gitignore* add list_*_plugins templates
* support MODULES/PLUGINS filters for make htmldocs
Add a 'PLUGINS=ssh' filter env var like MODULES to filter plugins to build docs for.
* fixup 'historical' version_added, skip plugins/loader.py
* Fix plugins_by_support ref link to new plugins/*/ location
* use :ref: for common_return_values, allow empty version_added
* warnings on missing doc info
* add a prefix to _random_choice
It was colliding with the target for random_choice plugin
* Revise and link inline to the lists of modules
* Fix jinja2 objects.inv fallback path
* Fix bolding of deprecation marker
* Change module_support to link to lists via :doc:
That links to the top of the page instead of a section.
* Add a short text for each list of maintained modules
* Change maintenance info to only display on core and network modules
This change fixes two issues with the generated return table:
1. When specifying a list of strings in the 'description' field of a
return value, it shows them in Python list syntax on the resulting
web page, e.g. `['a', 'b', 'c']`.
2. When specifying more than one line for the 'sample' field, the
result table gets damaged in the HTML output.
In addition, this change re-arranges the HTML tags produced in the
generated RST file such that they line up nicely and can better be
checked by humans for completeness.
Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>
* Add network value to support_by field.
* New support_by value, certified
* Deprecate curated in favor of certified
* Add conversion from 1.0 to 1.1 to metadata-tool
* Add supported by Red Hat field to ansible-doc output
* Big testing doc refactor
* Combine all the testing documentation in to one place to make it easier to find
* Convert everything to RST
* Create testing_network guide
* Create testing landing page
* For each section detail "how to run" and "how to extend testing"
* More examples
* Lots more detail
