Commit graph

65 commits

Author SHA1 Message Date
Dag Wieers
49afb3da34 Update Docsite edit (#51115)
* Improved template for docsite edits
2019-01-29 14:28:16 -05:00
Felix Fontein
4c473ecef4 Sort suboptions and subresults in docs. (#50315)
Fixes #50041.
2019-01-02 15:40:44 -06:00
Dag Wieers
76450fd1c2
Docs: Show parameter types (in purple) (#49966)
* 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
2018-12-20 18:34:32 +01:00
Dag Wieers
653c3da500 Fix document references in modules (#49892)
* Docs: Fixes internal module reference syntax for seealso
* Updates anchors and links
* Updates seealso in the docs for module **win_chocolatey**.
2018-12-17 10:20:06 -06:00
Dag Wieers
baf0ad2309 Docs: Add a "seealso" section to the module docs (#45949)
* 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
2018-12-12 14:19:58 -06:00
Jordan Borean
1599752f26 docs: add Support section for plugin types (#46520)
* docs: add Maintenance section for plugin types
* Added supported_by name in bold to match Status
2018-10-08 13:54:53 -05:00
Takashi Sugimura
069ba81386 remove unnecessary space (#46462)
kindly advised from jborean93
2018-10-04 10:47:31 +10:00
Dag Wieers
1ab411229a Get rid of duplicate status statement (#42885)
If a module was in status "preview", but it was not "supported"
(core/network) the message about the module being "preview" would be
repeated.
2018-07-26 11:32:49 -05:00
Brian Coca
b21c7c0232 create default status for when not provided
* also updated text to be 'plugin friendly' vs hardcoding modules

(cherry picked from commit 341a0f7b035588557d35fc12164a0f4031c786fe)
2018-07-09 11:44:01 -04:00
Felix Fontein
fb0b804988 Documentation: add parameter types, and version_added for return values and facts (#41999)
* Add types for parameters.

* Add version_added for return facts and return values.
2018-06-28 12:26:14 -05:00
Felix Fontein
0752dc12b7 Documentation: show non-string non-iterable defaults for choices (#40212)
* Also marking non-string defaults.

* Adding list filter from #37517 to plugin_formatter.

* Simplifying list test.

* Redistribute imports
2018-06-27 22:31:47 -04:00
Toshio Kuratomi
ad2e8dd6d8 Changes to support building docs with old jinja2
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.
2018-06-25 15:53:56 -07:00
Will Thames
50fe5dc090 Trim parameter documentation when generating docs (#38470)
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)
2018-06-21 13:51:58 +02:00
Felix Fontein
9f84c09bf3 Changing example code block language from yaml to yaml+jinja. (#40365) 2018-06-07 16:12:09 -05:00
Brian Campbell
fa5c0282a4 Use colspan on td instead of divs for hierarchical tables (#39948)
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.
2018-05-31 12:58:33 -05:00
Toshio Kuratomi
7ce1afebf0 Namespace the aliases ref target by plugin type (#38925) 2018-05-30 03:26:25 -04:00
Felix Fontein
f16933492d Fix problems in documentation generation (#40050)
* 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.
2018-05-15 16:19:04 +02:00
Alicia Cozine
0fef3f1b48 avoids not-in-toc errors with :orphan: 2018-04-23 12:14:43 -07:00
John R Barker
ebdf6d0fab
Add missing > to fix 'edit this document' link (#39067) 2018-04-20 11:31:17 +01:00
Salvatore Mesoraca
aaf2ff629d Fix formatting error in rst plugin template (#38956)
The hyperlink syntax used is wrong and the resulting
rendered documents have broken links.
2018-04-20 13:48:28 +05:30
Toshio Kuratomi
6ddc64bc7c Fixes for multiline doc descriotions breaking rst formatting
* strip whitespace to preserve indent level
* Make sure to indent subsequent lines of indentation
2018-04-19 11:37:37 -07:00
Toshio Kuratomi
a08459a814
Update info on python support (#38855)
* 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.
2018-04-18 13:04:47 -07:00
scottb
c97e508806
[WIP] disambiguating autogenerated module docs attempted fix of #38439. (#38890)
Disambiguates autogenerated module docs - fixes #38439.
2018-04-17 18:45:07 -07:00
Brian Coca
bdbb89378f
centralize doc/config plugin lists (#38775)
* 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
2018-04-16 09:29:49 -04:00
Toshio Kuratomi
25523666ce Modules that have a link to their own deprecated section need to use a different link syntax (#38697)
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
2018-04-12 17:24:14 -07:00
Dag Wieers
cdf9e39647 Fix the automatic docsite_pr label (#37999) 2018-04-05 10:48:37 -07:00
Toshio Kuratomi
8f1b5fc47b Add alias's as a :ref: target for modules
This is especially important for deprecated modules as we want to link
to those in porting guides and such.
2018-04-04 14:31:14 -07:00
Dag Wieers
69c0f96112 Fix nested parameters in module docs (#37793) 2018-03-22 14:33:51 -07:00
Brian Coca
06b70f1614 Revert "Add a few Jinja2 tests to simplify template (#37514)"
This reverts commit b8e07f0d6e.
2018-03-20 18:20:43 -04:00
Dag Wieers
b8e07f0d6e
Add a few Jinja2 tests to simplify template (#37514)
Add list test to simplify template
2018-03-20 23:08:55 +01:00
Dag Wieers
e691e07646 Fix boolean input and string-type validation 2018-03-15 12:39:39 -07:00
Dag Wieers
80ba7b7402 Various module doc fixes (#37256)
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
2018-03-12 13:50:52 -07:00
Dag Wieers
8f2c87231f Ensure the table spans the complete page width (#37129) 2018-03-08 10:48:42 -08:00
Dag Wieers
6636401246 Improve default values and choices in module docs (#36901)
* 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
2018-03-08 10:48:15 -08:00
Dag Wieers
eb52a88fb6 Improve module docs return values (#36943)
* 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
2018-03-06 10:46:19 +00:00
Dag Wieers
6601e78dfa
Wrong syntax 2018-03-01 03:07:03 +01:00
Dag Wieers
eae0aa0592 Automatically stuff reference in commit message (#36844)
* 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.
2018-02-28 21:14:57 +00:00
Dag Wieers
629278464f Improve contribute-message in document footer (#36841) 2018-02-28 09:21:24 -08:00
Dag Wieers
3b27d723fb Fix indentation of requirements (#36813)
Just discovered that the requirements were indented, whereas all other
lists were not. This makes them stand out for no good reason.
2018-02-28 17:16:18 +00:00
Dag Wieers
38abda544f Improve module docs wrt. required params (#36812)
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.
2018-02-28 09:00:56 -08:00
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