Commit graph

30 commits

Author SHA1 Message Date
Brian Coca
28015d8ae9 ensure cli dir exists before saving files to it 2018-02-13 17:43:26 -05: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
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
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
Brian Coca
b233f3f296 updated plugin docs (#30490)
* updated  docs

- for devs:
  - added inventory/vars section
  - made some updates to general section and other plugin types
- for users:
 - added 'user' plugin section to start describing the plugins
 - docs on types, what they are and how to use

- removed ref to deleted AUTHORS file
- corrected several typos/headers
- added descriptions to config.rst template
- ignore generated files for cli/plugins and config
- remove new generated files on `make clean`
- moved details from devguid and intro doc to plugin specific pages
- pretied up lookup notes
- changed precedence ref to not conflict config
- removed duplicate config data, as config is autogenerated and up to date
- put new plugins under playbooks
- added `pass` cause rst/python dislikes fractions
- removed dupe in .gitignore, alpha sorted to avoid moar dupes
- added try cause rst/python freaks out

* generate plugins into their own dir

only do plugins that support docs
use toctree from main plugins page
2017-09-22 23:19:50 -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
Brian Coca
1062f52f4c cleanup generated CLI rst 2017-09-18 16:20:49 -04:00
Adrian Likins
633263d535 add htmlsingle target (#30287)
For whatever reason, building the 'singlehtml' version of
the docs is much much faster than building the normal html
version.
2017-09-13 20:45:05 +00: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
Sam Doran
02a362e7de Replace rst extension with html in message (#29022) 2017-09-05 16:59:25 -04: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
Toshio Kuratomi
212499a489 On clean, remove the *_maintained.rst generated files 2017-08-22 11:52:30 -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
Matt Clay
789218c215 Initial ansible-test sanity docs. (#26775)
* Rename no-iterkeys test for consistency.

* Require docs for all ansible-test sanity tests.

* Initial ansible-test sanity docs.

* Fix capitalization of Python.

* Fix sanity code smell test false positives.

* Fix another code-smell false positive.
2017-07-14 14:24:45 +01:00
Matt Davis
365d06c538 add Makefile target for single HTML page (#25313) 2017-06-02 11:11:28 -07:00
Brian Coca
033fe5548b added epub entry for makefile 2017-05-01 13:41:04 -04:00
Toshio Kuratomi
4c7a2e2622 Enable intersphinx for python stdlib and jinja2
This setting allows us to reference jinja2 and python stdlib docs
via docutils refs instead of hardcoding urls.

Fixes #18039

Remove extraneous sphinx config
2017-04-25 12:26:40 -07:00
Brian Coca
424e1946f4 moved docs generation and templates to docs/ 2017-03-24 15:52:36 -04:00
Brian Coca
b606bcec04 Doc directives (#22524)
* draft docs for directives

* updated to document directives
2017-03-15 11:29:58 -04:00
Brian Coca
216e2c8813 leaving os immediate 2017-01-19 23:11:53 -05:00
Brian Coca
0803c638bb set cpus only if not set already 2017-01-19 23:09:55 -05:00
Brian Coca
c95bd7d9b0 fixed escape again 2017-01-19 23:08:01 -05:00
Toshio Kuratomi
e7505220d4 Need to define the OS variable at this level too 2017-01-19 19:53:29 -08:00
Brian Coca
339312a6b4 added missing file to cleanup 2017-01-18 14:34:01 -05:00
Brian Coca
712be24a74 Doc fixes (#20353)
* cleanup to reflect current builds

* consolidate templating docs and minor rewording

* new templating intro page

* fixed warnings as per feedback

* Update playbooks_filters.rst

Edited for clarity.

* Update playbooks_templating.rst

Light edits
2017-01-17 18:55:03 -08:00
Adrian Likins
a560a2d512 Use portable CPUS detect for docsite make default.
Some folks run 'make webdocs' from docs/docsite, so
use the portable CPUS detections as the default here as
well.
2017-01-13 14:41:14 -05:00
Adrian Likins
0381bc170c Docsite sphinx rm buildsite (and speed up docs build) (#20237)
Replace docs build-site.py with default-ish sphinx build

This seems to speed up docsite build _alot_. 

The Makefile.sphinx is the sphinx-quickstart generated makefile with a few changes.

The CPUS env var or 'nproc' output is used for the number of cpus passed to 'sphinx-build -j'
2017-01-13 14:32:27 -05:00
Brian Coca
d108a6f0fc fixed webdoc generation 2017-01-06 11:23:29 -05: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/Makefile (Browse further)