cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

adds stub API docs in a single file (#46663)

Browse source 
* adds stub API docs in a single file

(cherry picked from commit 9764f32513)
This commit is contained in:
Alicia Cozine 2018-10-11 09:15:24 -05:00 committed by Toshio Kuratomi
parent 68aa3e24a8
commit 86eb3b5b98
11 changed files with 118 additions and 612 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

232
docs/api/Makefile
View file

@ -1,232 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
LOGFILE = sphinx.log
FULL_TRACEBACKS = -T
CPUS ?= 4
VERBOSITY ?= -v
FORCE_REBUILD = -a -E
NITPICK ?=
SPHINXOPTS = -j $(CPUS) -w $(LOGFILE) $(FULL_TRACEBACKS) $(FORCE_REBUILD) $(NITPICK) $(VERBOSITY)
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
RSTDIR = rst
MODULES_PATH = ../../lib
EXCLUDE_PATHS = ../../lib/ansible/modules ../../lib/ansible/utils/module_docs_fragments ../../lib/ansible/module_utils/six
DOC_PROJECTS = "Ansible API"
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
.PHONY: clean
clean:
rm -rf $(BUILDDIR)/*
rm -rf $(RSTDIR)/*.rst
.PHONY: apidoc
apidoc:
sphinx-apidoc --module-first --doc-project $(DOC_PROJECT) --force --maxdepth 7 -o $(RSTDIR) $(MODULES_PATH) $(EXCLUDE_PATHS)
.PHONY: html
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: docs
docs: clean apidoc html
.PHONY: webdocs
webdocs: clean apidoc html
.PHONY: dirhtml
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
.PHONY: singlehtml
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
.PHONY: pickle
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
.PHONY: json
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
.PHONY: htmlhelp
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
.PHONY: qthelp
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Ansible.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Ansible.qhc"
.PHONY: applehelp
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
.PHONY: devhelp
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Ansible"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Ansible"
@echo "# devhelp"
.PHONY: epub
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
.PHONY: latex
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
.PHONY: latexpdf
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: latexpdfja
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: text
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
.PHONY: man
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
.PHONY: texinfo
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
.PHONY: info
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
.PHONY: gettext
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
.PHONY: changes
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
.PHONY: linkcheck
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
.PHONY: doctest
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
.PHONY: coverage
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
.PHONY: xml
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
.PHONY: pseudoxml
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

309
docs/api/conf.py
View file

@ -1,309 +0,0 @@
# -*- coding: utf-8 -*-
#
# Ansible documentation build configuration file, created by
# sphinx-quickstart on Fri Jun 3 17:34:17 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('../bin'))
sys.path.insert(0, os.path.abspath('../lib/ansible'))
import sphinx_rtd_theme
import alabaster
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
'sphinx.ext.graphviz',
'sphinx.ext.inheritance_diagram',
'alabaster',
]
# autodoc_default_flags = ['members', 'show-inheritance', 'inherited-members', 'undoc-members', ]
autodoc_default_flags = ['members', 'show-inheritance', 'undoc-members', ]
autoclass_content = 'both'
autodoc_member_order = 'bysource'
autodoc_mock_imports = ['xmltodict', 'winrm', 'redis', 'StricRedis']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Ansible'
copyright = u'2016, Red Hat'
author = u'Red Hat'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'2.3'
# The full version, including alpha/beta/rc tags.
release = u'1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
# html_theme = 'alabaster'
# html_theme_path = ['../docsite/_themes']
# html_theme = 'srtd'
html_short_title = 'Ansible Documentation'
# html_theme = "sphinx_rtd_theme"
# html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_theme_path = [alabaster.get_path()]
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
# html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
# html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
# html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
# html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'Ansibledoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
# Latex figure (float) alignment
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'Ansible.tex', u'Ansible Documentation',
u'Red Hat', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'ansible', u'Ansible Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'Ansible', u'Ansible Documentation',
author, 'Ansible', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
# texinfo_appendices = []
# If false, no module index is generated.
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False

8
docs/api/docs-requirements.txt
View file

@ -1,8 +0,0 @@
sphinx
# extensions
sphinxcontrib-napoleon
sphinxcontrib-inheritance
sphinx-rtd-theme
alabaster

22
docs/api/index.rst
View file

@ -1,22 +0,0 @@
.. ansible documentation master file, created by
sphinx-quickstart on Tue Jun 14 10:43:24 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to ansible's documentation!
===================================
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

7
docs/api/modules.rst
View file

@ -1,7 +0,0 @@
Ansible api
===========
.. toctree::
:maxdepth: 7
ansible

103
docs/docsite/rst/api/index.rst Normal file
View file

@ -0,0 +1,103 @@
:orphan:
*************************
Ansible API Documentation
*************************
The Ansible API is under construction. These stub references will be documented in future.
.. contents::
:local:
Attributes
==========
.. py:attribute:: AnsibleModule.params
The parameters accepted by the module.
.. py:attribute:: ansible.module_utils.basic.ANSIBLE_VERSION
.. py:attribute:: ansible.module_utils.basic.SELINUX_SPECIAL_FS
Deprecated in favor of ansibleModule._selinux_special_fs.
.. py:attribute:: AnsibleModule.ansible_version
.. py:attribute:: AnsibleModule._debug
.. py:attribute:: AnsibleModule._diff
.. py:attribute:: AnsibleModule.no_log
.. py:attribute:: AnsibleModule._selinux_special_fs
(formerly ansible.module_utils.basic.SELINUX_SPECIAL_FS)
.. py:attribute:: AnsibleModule._syslog_facility
.. py:attribute:: self.playbook
.. py:attribute:: self.play
.. py:attribute:: self.task
.. py:attribute:: sys.path
Classes
=======
.. py:class:: ansible.module_utils.basic.AnsibleModule
The basic utilities for AnsibleModule.
.. py:class:: AnsibleModule
The main class for an Ansible module.
Functions
=========
.. py:function:: ansible.module_utils.basic._load_params()
Load parameters.
Methods
=======
.. py:method:: AnsibleModule.log()
Logs the output of Ansible.
.. py:method:: AnsibleModule.debug()
Debugs Ansible.
.. py:method:: Ansible.get_bin_path()
Retrieves the path for executables.
.. py:method:: AnsibleModule.run_command()
Runs a command within an Ansible module.
.. py:method:: module.fail_json()
Exits and returns a failure.
.. py:method:: module.exit_json()
Exits and returns output.
Modules
=======
.. py:module:: ansible.module_utils
.. py:module:: ansible.module_utils.basic
.. py:module:: ansible.module_utils.url

8
docs/docsite/rst/dev_guide/debugging.rst
View file

@ -110,11 +110,11 @@ When you look into the debug_dir you'll see a directory structure like this::
* The :file:`ansible` directory contains code from * The :file:`ansible` directory contains code from
:mod:`ansible.module_utils` that is used by the module. Ansible includes :mod:`ansible.module_utils` that is used by the module. Ansible includes
files for any :`module:`ansible.module_utils` imports in the module but not files for any :mod:`ansible.module_utils` imports in the module but not
any files from any other module. So if your module uses any files from any other module. So if your module uses
:mod:`ansible.module_utils.url` Ansible will include it for you, but if :mod:`ansible.module_utils.url` Ansible will include it for you, but if
your module includes :mod:`requests` then you'll have to make sure that your module includes `requests <http://docs.python-requests.org/en/master/api/>`_ then you'll have to make sure that
the python requests library is installed on the system before running the the python `requests library <https://pypi.org/project/requests/>`_ is installed on the system before running the
module. You can modify files in this directory if you suspect that the module. You can modify files in this directory if you suspect that the
module is having a problem in some of this boilerplate code rather than in module is having a problem in some of this boilerplate code rather than in
the module code you have written. the module code you have written.
@ -139,7 +139,7 @@ module file and test that the real module works via :command:`ansible` or
The wrapper provides one more subcommand, ``excommunicate``. This The wrapper provides one more subcommand, ``excommunicate``. This
subcommand is very similar to ``execute`` in that it invokes the exploded subcommand is very similar to ``execute`` in that it invokes the exploded
module on the arguments in the :file:`args`. The way it does this is module on the arguments in the :file:`args`. The way it does this is
different, however. ``excommunicate`` imports the :func:`main` different, however. ``excommunicate`` imports the ``main``
function from the module and then calls that. This makes excommunicate function from the module and then calls that. This makes excommunicate
execute the module in the wrapper's process. This may be useful for execute the module in the wrapper's process. This may be useful for
running the module under some graphical debuggers but it is very different running the module under some graphical debuggers but it is very different

2
docs/docsite/rst/dev_guide/developing_modules_best_practices.rst
View file

@ -54,7 +54,7 @@ Python tips
* When fetching URLs, use ``fetch_url`` or ``open_url`` from ``ansible.module_utils.urls``. Do not use ``urllib2``, which does not natively verify TLS certificates and so is insecure for https. * When fetching URLs, use ``fetch_url`` or ``open_url`` from ``ansible.module_utils.urls``. Do not use ``urllib2``, which does not natively verify TLS certificates and so is insecure for https.
* Include a ``main`` function that wraps the normal execution. * Include a ``main`` function that wraps the normal execution.
* Call your :func:`main` from a conditional so you can import it into unit tests - for example: * Call your ``main`` function from a conditional so you can import it into unit tests - for example:
.. code-block:: python .. code-block:: python

18
docs/docsite/rst/dev_guide/developing_python_3.rst
View file

@ -68,15 +68,15 @@ they can be an array of text. Text is what we think of as letters, digits,
numbers, other printable symbols, and a small number of unprintable "symbols" numbers, other printable symbols, and a small number of unprintable "symbols"
(control codes). (control codes).
In Python 2, the two types for these (:class:`str` for bytes and In Python 2, the two types for these (:class:`str <python:str>` for bytes and
:class:`unicode` for text) are often used interchangeably. When dealing only :func:`unicode <python:unicode>` for text) are often used interchangeably. When dealing only
with ASCII characters, the strings can be combined, compared, and converted with ASCII characters, the strings can be combined, compared, and converted
from one type to another automatically. When non-ASCII characters are from one type to another automatically. When non-ASCII characters are
introduced, Python 2 starts throwing exceptions due to not knowing what encoding introduced, Python 2 starts throwing exceptions due to not knowing what encoding
the non-ASCII characters should be in. the non-ASCII characters should be in.
Python 3 changes this behavior by making the separation between bytes (:class:`bytes`) Python 3 changes this behavior by making the separation between bytes (:class:`bytes <python3:bytes>`)
and text (:class:`str`) more strict. Python 3 will throw an exception when and text (:class:`str <python3:str>`) more strict. Python 3 will throw an exception when
trying to combine and compare the two types. The programmer has to explicitly trying to combine and compare the two types. The programmer has to explicitly
convert from one type to the other to mix values from each. convert from one type to the other to mix values from each.
@ -95,7 +95,7 @@ Controller string strategy: the Unicode Sandwich
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In controller-side code we use a strategy known as the Unicode Sandwich (named In controller-side code we use a strategy known as the Unicode Sandwich (named
after Python 2's :class:`unicode` text type). For Unicode Sandwich we know that after Python 2's :func:`unicode <python:unicode>` text type). For Unicode Sandwich we know that
at the border of our code and the outside world (for example, file and network IO, at the border of our code and the outside world (for example, file and network IO,
environment variables, and some library calls) we are going to receive bytes. environment variables, and some library calls) we are going to receive bytes.
We need to transform these bytes into text and use that throughout the We need to transform these bytes into text and use that throughout the
@ -189,7 +189,7 @@ to the filesystem, it can be more convenient to transform to bytes right away
and manipulate in bytes. and manipulate in bytes.
.. warning:: Make sure all variables passed to a function are the same type. .. warning:: Make sure all variables passed to a function are the same type.
If you're working with something like :func:`os.path.join` which takes If you're working with something like :func:`python3:os.path.join` which takes
multiple strings and uses them in combination, you need to make sure that multiple strings and uses them in combination, you need to make sure that
all the types are the same (either all bytes or all text). Mixing all the types are the same (either all bytes or all text). Mixing
bytes and text will cause tracebacks. bytes and text will cause tracebacks.
@ -271,17 +271,17 @@ to make certain constructs act the same way on Python 2 and Python 3:
__metaclass__ = type __metaclass__ = type
``__metaclass__ = type`` makes all classes defined in the file into new-style ``__metaclass__ = type`` makes all classes defined in the file into new-style
classes without explicitly inheriting from :class:`object`. classes without explicitly inheriting from :class:`object <python3:object>`.
The ``__future__`` imports do the following: The ``__future__`` imports do the following:
:absolute_import: Makes imports look in :attr:`sys.path` for the modules being :absolute_import: Makes imports look in :data:`sys.path <python3:sys.path>` for the modules being
imported, skipping the directory in which the module doing the importing imported, skipping the directory in which the module doing the importing
lives. If the code wants to use the directory in which the module doing lives. If the code wants to use the directory in which the module doing
the importing, there's a new dot notation to do so. the importing, there's a new dot notation to do so.
:division: Makes division of integers always return a float. If you need to :division: Makes division of integers always return a float. If you need to
find the quotient use ``x // y`` instead of ``x / y``. find the quotient use ``x // y`` instead of ``x / y``.
:print_function: Changes :func:`print` from a keyword into a function. :print_function: Changes :func:`print <python3:print>` from a keyword into a function.
.. seealso:: .. seealso::
* `PEP 0328: Absolute Imports <https://www.python.org/dev/peps/pep-0328/#guido-s-decision>`_ * `PEP 0328: Absolute Imports <https://www.python.org/dev/peps/pep-0328/#guido-s-decision>`_

3
docs/docsite/rst/dev_guide/testing/sanity/use-argspec-type-path.rst
View file

@ -5,7 +5,6 @@ The AnsibleModule argument_spec knows of several types beyond the standard pytho
these is ``path``. When used, type ``path`` ensures that an argument is a string and expands any these is ``path``. When used, type ``path`` ensures that an argument is a string and expands any
shell variables and tilde characters. shell variables and tilde characters.
This test looks for use of :meth:`os.path.expanduser` in modules. When found, it tells the user to This test looks for use of :func:`os.path.expanduser <python:os.path.expanduser>` in modules. When found, it tells the user to
replace it with ``type='path'`` in the module's argument_spec or list it as a false positive in the replace it with ``type='path'`` in the module's argument_spec or list it as a false positive in the
test. test.

18
test/sanity/code-smell/docs-build.py
View file

@ -52,12 +52,6 @@ def main():
'unknown-interpreted-text-role': '^Unknown interpreted text role "[^"]*".$', 'unknown-interpreted-text-role': '^Unknown interpreted text role "[^"]*".$',
} }
ignore_codes = [
'reference-target-not-found',
]
used_ignore_codes = set()
for line in lines: for line in lines:
match = re.search('^(?P<path>[^:]+):((?P<line>[0-9]+):)?((?P<column>[0-9]+):)? (?P<level>WARNING|ERROR): (?P<message>.*)$', line) match = re.search('^(?P<path>[^:]+):((?P<line>[0-9]+):)?((?P<column>[0-9]+):)? (?P<level>WARNING|ERROR): (?P<message>.*)$', line)
@ -96,20 +90,8 @@ def main():
else: else:
code = 'error' code = 'error'
if code == 'not-in-toc-tree' and path.startswith('docs/docsite/rst/modules/'):
continue # modules are not expected to be in the toc tree
if code in ignore_codes:
used_ignore_codes.add(code)
continue # ignore these codes
print('%s:%d:%d: %s: %s' % (path, lineno, column, code, message)) print('%s:%d:%d: %s: %s' % (path, lineno, column, code, message))
unused_ignore_codes = set(ignore_codes) - used_ignore_codes
for code in unused_ignore_codes:
print('test/sanity/code-smell/docs-build.py:0:0: remove `%s` from the `ignore_codes` list as it is no longer needed' % code)
def simplify_stdout(value): def simplify_stdout(value):
"""Simplify output by omitting earlier 'rendering: ...' messages.""" """Simplify output by omitting earlier 'rendering: ...' messages."""