Commit graph

59 commits

Author SHA1 Message Date
Wojciech Sciesinski
49e7f9afe2
Link the testing documentation to the module documenting page (#67248) 2020-02-10 15:30:04 -05:00
Sandra McCann
4dd2513371
add info on creating doc fragments in a collection (#67171)
* add info on creating doc fragments in a collection
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
2020-02-10 10:23:28 -06:00
kaorihinata
3ca4580cb4 Allow no_log=False to silence the no_log warnings for module parameters (#64733)
As AnsibleModule._log_invocation is currently implemented, any parameter
with a name that matches PASSWORD_MATCH triggers the no_log warning as a
precaution against parameters that may contain sensitive data, but have not
been marked as sensitive by the module author.

This patch would allow module authors to explicitly mark the aforementioned
parameters as not sensitive thereby bypassing an erroneous warning message,
while still catching parameters which have not been marked at all by the
author.

Adds tests for various no_log states including True, False, and None (as
extracted by AnsibleModule._log_invocation) when applied to an argument with
a name that matches PASSWORD_MATCH.

Fixes: #49465 #64656
2020-01-09 16:47:57 -05:00
Evgeni Golov
057e137998 clarify returned value of RETURN nlock (#65724) 2019-12-12 17:12:38 -06:00
Felix Fontein
0bf9146b29 Document 'elements' for module option and return value documentation. (#64075) 2019-11-04 15:21:07 -05:00
Sandra McCann
bdd0fac606 add note about collection links (#63346) 2019-10-11 08:27:26 -05:00
Sam Doran
041c52d629 Add info about layering properties 2019-09-12 18:55:13 -07:00
Sam Doran
5deb01c84d Remove suggestion to go caving 2019-09-12 18:55:13 -07:00
Sam Doran
9b348e690c Improve documentation on doc fragments
Add information and examples on how to use additional properites from a doc fragment
2019-09-12 18:55:13 -07:00
Evgeni Golov
c1773d5d2b document suboptions for type:list options too (#62177) 2019-09-12 16:00:06 -04:00
Toshio Kuratomi
46f633598e Add guidelines for when to use a doc_fragment (#61828) 2019-09-12 12:55:50 -04:00
Alicia Cozine
118cf3ece6
Cloud dev docs to rst (#56485)
* Moves developer docs for AWS, ovirt, and openstack modules out of lib/ansible/, integrates them with dev_guide, with abadger's fix to make python snippets pass rstcheck
2019-05-16 09:05:12 -05:00
Alicia Cozine
3c8d8b1509 should have gone into 52373 (#56306) 2019-05-10 10:59:50 -04:00
Dag Wieers
eac7f1fb58 dev_guide: Various small updates (#53273)
* Document the clarifications that I usually remark when doing reviews
* Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst

Co-Authored-By: dagwieers <dag@wieers.com>
2019-05-09 18:44:28 -05:00
Daniel Hagan
e114d06801 Minor formatting fix in developing_modules_documenting.rst (#54785)
* developing_modules_documenting.rst - fix formatting error

* developing_modules_documenting.rst - remove errant whitespace from last commit
2019-04-04 08:52:31 +01:00
David Passante
40af4a144d Update an example in documentation fields (#53760)
According to the `Linking within module documentation` section, the right syntax should be `I(state=present)`.
2019-03-14 19:14:08 -05:00
Brian Coca
96b3ef5553
Doc fragments to plugins (#50172)
* promote doc_fragments into actual plugins

  change tests hardcoded path to doc fragments
  avoid sanity in fragments
  avoid improper testing of doc_fragments
  also change runner paths
 fix botmeta
 updated comment for fragments
 updated docs
2019-01-23 20:03:47 -05:00
Dag Wieers
1fb2165bd8
Fix typo
+label: docsite_pr
2019-01-22 15:45:01 +01:00
Alicia Cozine
90a6771bc8
removes space from example of L(link) syntax (#49908) 2018-12-14 09:15:57 -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
Alicia Cozine
4219d25fc7 Add docs about contributing to docs (#46481)
* adds page on community contributions to docs
2018-10-24 11:14:01 -04:00
Alicia Cozine
9a76441c02
rewrite of the developer guide, part 1 (#45179)
* rewrite of the developer guide, part 1
2018-09-07 08:57:36 -05:00
Andreas Olsson
00e5123e4c Update documentation based on 301 permanent redirects (#43675) 2018-08-13 14:54:14 -05:00
John R Barker
6366df700d Document module links (#42308) 2018-07-05 14:19:09 -05:00
John R Barker
d962611528 Allow documentation of module options type (#42285)
* Allow documentation of module options

Pass through the `type` of a modules option so it's displayed on the
html module docs

* docs
2018-07-05 09:57:58 -04:00
Alicia Cozine
bbfd6c6ab1 Internal refs (#39094)
* fixes community refs

* fixes appendix refs

* fixes scenario refs, keeps ACI guide link to devel

* fixes windows refs

* fixes user guide refs

* fixes dev guide refs
2018-04-20 12:17:02 -07:00
scottb
381359a8f8
Doc build warning/broken link clean-a-palooza (#37382)
* Doc build warning/broken link clean-a-palooza, WIP commit 1.

* Fixed broken anchor

* Fixing additional broken links; converting from doc to ref.

* Fix anchor
2018-03-14 12:44:21 -07:00
John R Barker
985f09270d
Ability to link to other pages from plugin docs (#37009)
Support relative links
2018-03-05 15:16:58 +00:00
Brian Coca
3eff279dd7 updates to module testing (#36043)
* updates to module testing

gives those using internal modules an alternative

* Copy edit
2018-02-16 10:04:10 -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
Pilou
b66863abf0 dev_guide: don't ask to use '© Ansible Project' (#34704)
contributor don't sign any copyright assignment, then this makes no
sense.
2018-01-11 14:23:36 +10:00
Pilou
6a6f5129a9 dev_guide: fix a slip (#34143)
replace 'Formatting options' with 'Formatting functions'
2017-12-26 10:18:09 +00:00
Will Thames
5f29cd5e60 Add validation test for new copyright (#32919)
* Update validation test for new copyright

Ensure new modules without the new copyright header fail
validation
Ensure existing modules without copyright in top 20 lines fail

* Add documentation of 108 error

Create label in developing modules documentation so that
the validation page can point to it

* Ensure new style copyright header passes test!
2017-12-16 09:23:54 -08:00
Michihito Shigemura
b7b8c669a3 Fix typo in dev_guide/developing_modules_documenting (#31120) 2017-09-30 17:19:09 -07:00
Dag Wieers
e63d949951 Add a blank line, and use the Copyright format as used during rewrite
So there is a discrepancy between the dev guide and what has been changed on disk by toshio.
Not a big deal, but needlessly confusing.
2017-09-27 20:44:22 +02:00
Monty Taylor
700a032bf1 Add an example of complex return argument (#28610) 2017-09-20 15:51:45 +01:00
Toshio Kuratomi
c82cf791dd Add a code-smell test for smart quotes and remove smart quotes from all files 2017-09-18 16:49:16 -07:00
Toshio Kuratomi
8a2f069468 Document boolean default value treatment (#30062)
* Consistency and document treatment of default bool values

* Document that default bool values can be any Ansible recognized bool.
  choose the one that reads better in context
* For fragments used by the copy module, make bool types use type=bool and not choices

* Edit for clarity
2017-09-14 13:27:16 -07:00
Pilou
d67d202227 Fix typo: s/certfied/certified/ (#28951) 2017-09-02 13:46:46 -07:00
Dag Wieers
ccb6b39f45 Corrected RETURNS -> RETURN 2017-08-28 10:09:21 +02:00
Sam Doran
b7aa38c0d8 Minor fixes to Developer Docs (#28302)
* Grammar and formatting corrections

Indent JSON code example.
Double backticks for inline code examples.

* Remove trailing spaces

* CI fixes
2017-08-16 17:56:53 -07: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
Branko Majic
f78baa1300 Implement ability to limit module documentation building (#24576)
* Implement ability to limit module documentation building:

- Added new option to plugin_formatter.py to support passing-in a list of
  modules for which the documentation should be built.
- Updated docuemtnation Makefile to allow specifying list of modules via
  environment variables (defaulting to all modules).
- Update instructions for building documentation and module development to
  include commands and description of limiting module documentation builds.

* Updated implementation for limiting module documentation building:

- Pass list of modules (or None) to list_modules function instead of string.
- Move conversion of module list to argument parsing code.
- No special keywords. Default ("") means build all modules. For no modules just
  specify non-existing module name.
- Updated documentation to reflect the changes.

* Updated implementation for limiting module documentation building:

- Use better default value, and don't treat "" as special case.
- Conditionally invoke different variants of command in Makefile instead of
  using special value "".

* Minor edits

Wording tweak
2017-08-04 13:10:36 -07:00
Ryan Brown
beca565c79 [Docs] Add note on module development about the copyrights (#26812)
* Add note on module development about the copyrights

This matches what's in CODING_GUIDELINES.md as of July 2017

* Add recommendation for standardizing on `Copyright (c) 2017 Ansible Project`

* s/with/should have/

* Fix more unicode
2017-07-19 06:58:52 -04:00
Pilou
4b3d6dfa8a Use pycodestyle instead of pep8 (#25947) 2017-07-13 11:46:31 -07:00
John R Barker
5551e87755 RETURNS can include version_added (#25810) 2017-06-16 20:17:38 +01:00
Matt Clay
9178e176b5 Limit sphinx version on python 2.6. (#24678)
* Limit sphinx version on python 2.6.
* Fix issues identified by rstcheck.
2017-05-17 01:00:15 +08: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
Scott Butler
5591d639f5 Fixed broken link. 2017-03-31 11:17:53 -07:00
Dylan Silva
9dae697997 Updates to docs for metadata. (#22667)
* Updates to docs for metadata.

* Update developing_modules_documenting.rst
2017-03-15 15:34:00 -07:00