Commit graph

42 commits

Author SHA1 Message Date
Toshio Kuratomi
9dda393d70
Collections docs generation (#59761)
* Build documentation for Ansible-2.10 (formerly known as ACD).

Builds plugin docs from collections whose source is on galaxy

The new command downloads collections from galaxy, then finds the
plugins inside of them to get the documentation for those plugins.

* Update the python syntax checks
  * docs builds can now require python 3.6+.

* Move plugin formatter code out to an external tool, antsibull-docs.
  Collection owners want to be able to extract docs for their own
  websites as well.
* The jinja2 filters, tests, and other support code have moved to antsibull
* Remove document_plugins as that has now been integrated into antsibull-docs

* Cleanup and bugfix to other build script code:
  * The Commands class needed to have its metaclass set for abstractmethod
    to work correctly
  * Fix lint issues in some command plugins

* Add the docs/docsite/rst/collections to .gitignore as
  everything in that directory will be generated so we don't want any of
  it saved in the git repository
* gitignore the build dir and remove edit docs link on module pages

* Add docs/rst/collections as a directory to remove on make clean
* Split the collections docs from the main docs

* remove version and edit on github
* remove version banner for just collections
* clarify examples need collection keyword defined

* Remove references to plugin documentation locations that no longer exist.
  * Perhaps the pages in plugins/*.rst should be deprecated
    altogether and their content moved?
  * If not, perhaps we want to rephrase and link into the collection
    documentation?
  * Or perhaps we want to link to the plugins which are present in
    collections/ansible/builtin?

* Remove PYTHONPATH from the build-ansible calls
  One of the design goals of the build-ansible.py script was for it to
  automatically set its library path to include the checkout of ansible
  and the library of code to implement itself.  Because it automatically
  includes the checkout of ansible, we don't need to set PYTHONPATH in
  the Makefile any longer.

* Create a command to only build ansible-base plugin docs
  * When building docs for devel, only build the ansible-base docs for
    now.  This is because antsibull needs support for building a "devel
    tree" of docs.  This can be changed once that is implemented
  * When building docs for the sanity tests, only build the ansible-base
    plugin docs for now.  Those are the docs which are in this repo so
    that seems appropriate for now.
2020-07-17 13:07:35 -07:00
Sandra McCann
75b088d6a9
Remove extra Ansible in network automation section header (#67828) 2020-02-27 15:28:34 -06:00
Sandra McCann
b2fc12a29f clean up network toc (#65264) 2019-11-25 15:17:49 -06:00
Sandra McCann
af64e9ce6a add Automation Hub stub page (#65261)
* add Automation Hub stub page

* implement feedback
2019-11-25 13:58:01 -06:00
Sandra McCann
ee8a088205 combine galaxy.com install roles details (#63486)
* combine galaxy.com install roles details
* flatten dev guide and user guide for galaxy
2019-10-28 14:59:14 -05:00
Sandra McCann
ae265bc546 Move galaxy appendix info to a new Galaxy section (#63356)
* start galaxy docs restructure
* shared snippets in txt files
* moved all content to galaxy section
2019-10-11 13:19:44 -05:00
Alicia Cozine
941a9b68fc Docs: User guide overhaul, part 1 (#63056) 2019-10-08 13:46:38 -04:00
Brian Coca
c2469648e4 Docs on general precedence (#50201)
* Add docs/docsite/rst/reference_appendices/general_precedence.rst

Co-Authored-By: Sandra McCann <samccann@redhat.com>
2019-07-09 12:14:40 -05:00
Alicia Cozine
a4d0bc2c43
Shortens Scenario Guides, incorporates vmware guide (#54554)
* Shortens Scenario Guides, incorporates vmware guide

* adds links from network scenario guides to other network docs
2019-04-04 11:58:30 -05:00
Matt Davis
4d3a6123d5
Python interpreter discovery (#50163)
* Python interpreter discovery

* No longer blindly default to only `/usr/bin/python`
* `ansible_python_interpreter` defaults to `auto_legacy`, which will discover the platform Python interpreter on some platforms (but still favor `/usr/bin/python` if present for backward compatibility). Use `auto` to always use the discovered interpreter, append `_silent` to either value to suppress warnings.
* includes new doc utility method `get_versioned_doclink` to generate a major.minor versioned doclink against docs.ansible.com (or some other config-overridden URL)

* docs revisions for python interpreter discovery

(cherry picked from commit 5b53c0012ab7212304c28fdd24cb33fd8ff755c2)

* verify output on some distros, cleanup
2019-02-27 23:52:02 -08:00
Alicia Cozine
e97391b7ab updates language about documentation versions and releases on index page (#46465) 2018-10-04 15:26:37 -04:00
Sandra McCann
df3655968f Infoblox scenario guide (#45664)
* creates infoblox scenario guide
* adds link to infoblox guide from modules
* adds WAPI to prerequisites
2018-09-24 14:25:01 -05:00
Alicia Cozine
4264be2b18 Remove more docs build errors (#45364)
* orphans testing pages to avoid not-in-toctree errors

* orphans various pages pending reorg

* adds module_utils and special_vars to main TOC

* uses a glob for scenario_guide TOC

* normalize and Sentence-case headings on community pages, typos

* re-orgs community TOC, adds all pages to toctree

* removes scenario guides index page

* adds style guide to community index

* basic update to style guide

* fix typo that created a new error

* removes not-in-toctree from ignore errors list

* leave removing files for future cleanup task
2018-09-11 17:51:47 +01:00
Kevin Breit
ec3ce1f39c Meraki scenario guide (#41827)
* Initial commit for the Meraki scenario guide

* Added Meraki guide to indexes, fixed an error

* Added common parameters to scenario guide

* Add additional information for first draft
- Added very common parameters everyone uses.
- Documented common format for returned data from Meraki.
- High level explanation of error handling.

* Fix .rst formatting error

* Added section about handling returned data. More to come.

* Small formatting changes
2018-09-10 14:59:23 +02:00
Yanis Guenane
857a553fa1 Vultr: Create the Vultr Guide (#44515) 2018-08-31 10:42:07 -04:00
Sandra McCann
1c42198f1e fixed network automation index issues (#44732)
* fixed network automation index issues

* replace :doc: with :ref:

* fixed anchor misspelling

* fix toc/nav issue -do not put toctree under a subheader
2018-08-29 15:37:00 +02:00
Tina
0186449e7b Update index.rst (#43490)
Update mention of 'current released version'

+label: docsite_pr
2018-08-16 18:53:47 -04:00
Abhijeet Kasurde
d1c0b7a597 VMware: restructure docs (#43065)
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
2018-07-30 11:00:00 -05:00
scottb
0c0dc8d9fc
Adds documentation structure and stubs for new VMWare guide (#39246)
* Adding initial skeleton of VMWare docs

* Updated product name capitaliztion; ready for initial PR.

* Add few files and updated some links

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

* Fixed duplicate anchor tag
2018-05-03 08:05:28 -07:00
Alicia Cozine
becc2a0347 adds index page for roadmaps to support internal links (#39109)
* adds index page for roadmaps to support internal links

* includes only roadmaps index page in TOC
2018-04-23 12:22:44 -07:00
Alicia Cozine
64dcc7def0 Fixes more rST errors (#39042)
* removes include, avoids duplicate label rST warnings

* reduces literal_block errors on playbooks_filters

* addresses TOC errors

* ref error on modules page

* trying ref for list_of_database_modules
2018-04-19 17:02:48 -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
scottb
57da6319e1
Adds VMWare to TOC; sort scenario guides alphabetically (#37661) 2018-03-20 12:15:15 -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
Alicia Cozine
51a010a696 Network Getting started docs (#36337)
* first draft of getting started guide
2018-02-22 20:43:04 +00:00
scottb
1f609f8be3
Cleaned up some scenario guide titles and TOC placement. (#36225) 2018-02-14 23:14:22 -08:00
scottb
c5dd0d97af
Relocate ACI guide and add to TOC (#36208) 2018-02-14 14:00:18 -08:00
scottb
c10080bfba
Followup to docs refactor pull request #36067 - fixes gitignore and c… (#36120)
* Followup to docs refactor pull request #36067 - fixes gitignore and cleanup in makefile; removes some generated files; moves a straggler to the appropriate subdirectory.

* Fixed some stragglers

* Removed redundant module entries

* Delete generated RST files.
2018-02-13 10:52:13 -08: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
Alicia Cozine
9dad5d6b7f creates structure for network docs (#35514) 2018-01-31 10:01:55 -08:00
scottb
f8f34c7bab
Moved generated module RSTs to their own directory. (#33966)
* Moved generated module RSTs to their own directory.

* WIP commit - fixed conflict with conf.py exclude_patterns by renaming module RST output directory to 'module_docs'.

* Added new directory to formatter module links; aded new module directory to makefile clean.

* Removed illegal comment from block.
2017-12-21 01:47:39 -08:00
Greg DeKoenigsberg
c5b4d53c09 Update index.rst to point to new community guide (#32263)
We made this change a couple of months ago, deprecating community.html in favor of community/index.html and its full guide, but the change was never made here in the index.
2017-10-27 17:48:14 +01:00
Jordan Borean
f2fed10ad8 update Windows docs (#30783)
* first round of splitting and expanding Windows docs

* Added info about WinRM and started the usage page

* more details onf usage around command/shell

* added more info

* missed a page

* added info about hotfix and ps upgrade script

* Added DSC information

* filled in FAQ and fixed up links

* changes per PR review and typo fixes found by myself

* fixed sanity check

* updated external script URLS

* Edits

* Edits

* Edits

* Copy edits.

* More copy edits.

* Added info about becoming a local service account

* some formatting changes on become and DSC indent fix

* Copy edits/rewrites

* Copy edits/rewrites

* minor updates to UAC text, typos

* minor wording updates

* minor wording tweaks/typos

* minor wording tweaks/typos

* minor tweaks/typos

* fix indent issue

* fix title underline length

* fix quote issue
2017-10-12 18:40:47 -07:00
Brian Coca
5220f30244 decelerate docs! 2017-09-20 17:30:59 -04: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
Adrian Likins
89c973445c generate rst doc pages for command line tools (#27530)
* let generate_man also gen rst pages for cli tools
* make template-file, output-dir, output format cli options for generate_man
* update main Makefile to use generate_man.py for docs (man pages and rst)
* update vault docs that use :option:
* Edits based on
6e34ea6242 and
a3afc78535

* add a optparse 'desc' to lib/ansible/cli/config.py 

  The man page needs a short desc for the 'NAME' field
  which it gets from the option parse 'desc' value.

  Fixes building ansible-config man page.

* add trim_docstring from pep257 to generate_man

  use pep258 docstring trim function to fix up any indention
  weirdness inherit to doc strings (ie, lines other than
  first line being indented.

* Add refs to cli command actions

To reference ansible-vaults --vault-id option, use:

:option:`The link text here <ansible-vault --vault-id>`

or:

:option:`--vault-id <ansible-vault --vault-id>`

To reference ansible-vault's 'encrypt' action, use:

:ref:`The link text here <ansible_vault_encrypt>`

or most of the time:

:ref:`ansible-vault encrypt <ansible_vault_encrypt>`
2017-09-07 15:44:20 -04:00
Scott Butler
a9f82f8a8a Fixed incorrect version numbers. 2017-09-01 15:42:02 -07:00
Adrian Likins
28b9dc4bed Vault docs (#26979)
* start rst docs for ansible-vault encrypt_string

* wip, vault format docs

(sorta markdown ish atm)

* wip - formatting

* wip, vault docs

* Fix refs to other docs for now

fixing default_role in conf.py will remove need
for this

* add 'ref' to cli names

* more vault docs

* wip, misc fixes

* add some encrypt_string examples

* Fix up rstcheck warnings

The code blocks in question included the output that would
be echo'ed from running the command, which isnt valid bash.

* fix formatting and rstcheck warnings about code-block

* Add envvar ref for ANSIBLE_VAULT_PASSWORD_FILE

* fix doc title

* Fixed title underline
2017-08-31 12:18:38 -07:00
Adrian Likins
8035e68d44 Generate a rst for config and env options from base.yml (#28739)
* wip, gen docs from config/base.yml

* wip

* dont change conf.py here

* cleanup, add dump_config --template-file cli opt

* some desc are string, some are lists...

TODO: fix base.yml so it is consistent

* Filter out TODO and empty descriptions
2017-08-31 10:11:05 -04:00
John R Barker
df58d943d3 Docs porting guides 2.0 & 2.3 (#27632)
* Create new "Porting Guide" section

Create new landing page
Add porting_guide_2.3

* correct CHANGELOG

* Document blocks

* Document named blocks

* OpenBSD & async action plugins

* OpenBSD & async action plugins

* versioadded for name

* review comments
2017-08-02 21:36:17 +01:00
David Moreau-Simard
e2d874c744 Improve release and development cycle documentation
This commit:
- Adds a table highlighting the status of each version and provides
  a link to each major release's changelog
- Re-inforces how stable versions are maintained and for how long
- Moves this documentation out of the developer tree (this is
  interesting for users too!) while keeping a link there.
2017-07-25 23:38:08 -07:00
Brian Coca
57f8b791d6 consolidated docs
point to new doc locations
removed non existing dirs
2017-01-06 09:16:59 -05:00
Renamed from docsite/rst/index.rst (Browse further)