Commit graph

75 commits

Author SHA1 Message Date
Dag Wieers
974c50a417 Move notes higher up in order (#36815)
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.
2018-02-28 08:58:49 -08:00
Dag Wieers
4ff0317f3e
Improve module doc parameter list (#36688)
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
2018-02-25 16:40:27 +01:00
Dag Wieers
7cf08e9986
Improve parameter required values and ref fix (#36680)
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
2018-02-24 22:36:08 +01:00
Dag Wieers
3016bc7351
Asorted docs fixed (#36672)
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
2018-02-24 14:06:12 +01:00
Dag Wieers
ba370b178d
docsite: Add 'Edit on GitHub' for module docs (#36667)
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 !
2018-02-24 03:57:37 +01:00
scottb
373b1dcf59
Core Docs Refactor and Redesign (#36067)
* 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
2018-02-13 07:23:55 -08:00
John R Barker
a23c95023b
Module deprecation: docs, scheme and tests (#34100)
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()
```
2018-01-30 12:23:52 +00:00
Dag Wieers
1719267779 Sort arguments and return values in module docs
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.
2018-01-25 18:34:27 -08:00
Abhijeet Kasurde
f58d9da703 Update link in common footer (#34397)
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
2018-01-03 20:52:14 -08:00
John R Barker
7381554e42 Compact documentation (#34081)
Before this fix lists of `documentation:` were in individual <p> tags
causing a lot of whitespace on the rendered _module.html pages.
2017-12-20 20:49:09 +10:00
Jordan Borean
0880297909 fix options output for bool type (#34074) 2017-12-20 09:48:17 +00:00
Wolfgang Felbermeier
817a5efff9 Fix css of elbow indentation for firefox (#33225) 2017-11-27 13:13:17 +10:00
Wolfgang Felbermeier
496ce388ab documentation: render nested return dicts for more then one level (#33143)
* 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
2017-11-22 16:53:53 -05:00
Brian Coca
afc460c943 tollerate 'string' descriptions 2017-11-14 11:18:48 -05:00
Ed Santiago
47fb002c88 (minor) fix broken link, awkward phrasing (#32085)
* (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
2017-10-27 21:39:23 -07:00
Brian Coca
2ed46e04f4 more updates to plugin/config generation (#30787)
* 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
2017-10-11 00:15:25 -04:00
sduthil
15dffe04dd fix misformatted docsite link (#31384)
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>".
2017-10-05 18:52:30 -07:00
Adrian Likins
da15cf1f54 Generate plugin rst (#28901)
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
2017-09-19 11:14:27 -04:00
Toshio Kuratomi
40ea448c7b Misc docs fixes
* 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
2017-08-22 11:52:30 -07:00
Jiri Tyr
5660b18b6a Adding missing period into the module doc template 2017-08-21 14:20:08 -04:00
Andreas Maier
b900f4a3be Fixed return table in module docs generated by plugin_formatter.py (#25329) (#25330)
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>
2017-08-18 15:38:55 -04:00
Toshio Kuratomi
af2073d057 metadata 1.1
* 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
2017-08-15 23:12:08 -07:00
John R Barker
f338dd2fc3 Render returned dictionaries Fixes #24775 (#24777)
plugin.rst.j2 was out of sync with syntax validator
2017-05-18 15:13:33 +01:00
John R Barker
ecbf8e933a Docs how to test (2nd) (#24094)
* 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
2017-04-28 09:08:26 +01:00
Brian Coca
424e1946f4 moved docs generation and templates to docs/ 2017-03-24 15:52:36 -04:00
Renamed from hacking/templates/rst.j2 (Browse further)