Commit graph

94 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
Sandra McCann
3eec7f1820 Modules tocfix (#51077)
define & create subcategories, output by category and subcat
2019-01-23 13:21:23 -06: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
Pilou
7fd8d8d8c7 doc: fix link to ansible-config (#49597) 2018-12-06 10:00:48 -05:00
Brendan Good
475844d1ae Fix man page template typo. (#48585)
changed from 'direcotry' to 'directory'.
2018-11-13 11:46:11 +05:30
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
Toshio Kuratomi
30662bedad
Only print warning when ansible.cfg is actually skipped (#43583)
Only print warning when ansible.cfg is actually skipped

* Also add unittests for the find_ini_config_file function
* Add documentation on world writable current working directory
  config files can no longer be loaded from a world writable current
  working directory but the end user is allowed to specify that
  explicitly.  Give appropriate warnings and information on how.

Fixes #42388
2018-08-03 10:39:33 -07: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
Brian Coca
b6f2aad600 ignore ansible.cfg in world writable cwd (#42070)
* ignore ansible.cfg in world writable cwd
 * also added 'warnings' to config
 * updated man page template
2018-06-29 16:46:10 -07: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
Pilou
3f5f5faec6 doc: config intro, add link to searched locations (#39614) 2018-05-25 00:29:29 -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
c8a9b411bc
Last docs link fixes (#39391)
* should not need <>, but fails without

* adds anchor to keywords page, uses it on plugins pages

* fixes envvar link errors

* harmonize file name and ref name as python_3

* removes undefined-lable from ignore list
2018-04-27 13:21:39 -05:00
Alicia Cozine
4b52a54e18 Reduce warnings (#39254)
* removes FAQ links; no entries exist for linked config settings

* fixes various anchors and links

* addresses abadger comments, thanks

* marks orphan pages, avoids TOC errors

* adds links for remote_tmp setting to FAQ
2018-04-25 11:18:52 -07:00
Alicia Cozine
0fef3f1b48 avoids not-in-toc errors with :orphan: 2018-04-23 12:14:43 -07:00
Matt Clay
c262dbfd30 Use https for links to ansible.com domains. 2018-04-23 11:33:56 -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
Toshio Kuratomi
8cdd75a09f Some more fixes for the docs :ref: disambiguation
The big one is that we needed to set plugin_type when we processed the by_support template.

Also added to list_of_CATEGORY_plugins page (which might not be used)
and corrected a place where I did module_name instead of name_module
2018-04-18 10:06:01 -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
Scott Butler
62c2b9a544 Removes modules from TOC, speeding up build time and reducing doc disk space requirements. 2018-04-04 20:36:01 -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
Matt Martz
a89d0d0919
Ensure that arguments for sub commands are properly indented (#37992) 2018-04-03 10:56:12 -05:00
Joseph Herlant
00a7ff7974 Move man pages generations to rst2man (#37861) 2018-03-26 16:28:28 -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