From 86eb3b5b984b16df37bf4533cbd36cb583211f5a Mon Sep 17 00:00:00 2001 From: Alicia Cozine <879121+acozine@users.noreply.github.com> Date: Thu, 11 Oct 2018 09:15:24 -0500 Subject: adds stub API docs in a single file (#46663) * adds stub API docs in a single file (cherry picked from commit 9764f325132b4fb04d43185bfbf08e93e3141d51) --- docs/api/Makefile | 232 ---------------- docs/api/conf.py | 309 --------------------- docs/api/docs-requirements.txt | 8 - docs/api/index.rst | 22 -- docs/api/modules.rst | 7 - docs/docsite/rst/api/index.rst | 103 +++++++ docs/docsite/rst/dev_guide/debugging.rst | 8 +- .../developing_modules_best_practices.rst | 2 +- docs/docsite/rst/dev_guide/developing_python_3.rst | 18 +- .../testing/sanity/use-argspec-type-path.rst | 3 +- 10 files changed, 118 insertions(+), 594 deletions(-) delete mode 100644 docs/api/Makefile delete mode 100644 docs/api/conf.py delete mode 100644 docs/api/docs-requirements.txt delete mode 100644 docs/api/index.rst delete mode 100644 docs/api/modules.rst create mode 100644 docs/docsite/rst/api/index.rst (limited to 'docs') diff --git a/docs/api/Makefile b/docs/api/Makefile deleted file mode 100644 index caf765ed7b..0000000000 --- a/docs/api/Makefile +++ /dev/null @@ -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 ' where 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." diff --git a/docs/api/conf.py b/docs/api/conf.py deleted file mode 100644 index f52a00ec55..0000000000 --- a/docs/api/conf.py +++ /dev/null @@ -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 -# " v 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 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 diff --git a/docs/api/docs-requirements.txt b/docs/api/docs-requirements.txt deleted file mode 100644 index 22a38a8228..0000000000 --- a/docs/api/docs-requirements.txt +++ /dev/null @@ -1,8 +0,0 @@ -sphinx - -# extensions -sphinxcontrib-napoleon -sphinxcontrib-inheritance - -sphinx-rtd-theme -alabaster diff --git a/docs/api/index.rst b/docs/api/index.rst deleted file mode 100644 index 54ebdce808..0000000000 --- a/docs/api/index.rst +++ /dev/null @@ -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` - diff --git a/docs/api/modules.rst b/docs/api/modules.rst deleted file mode 100644 index fab814b9cc..0000000000 --- a/docs/api/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -Ansible api -=========== - -.. toctree:: - :maxdepth: 7 - - ansible diff --git a/docs/docsite/rst/api/index.rst b/docs/docsite/rst/api/index.rst new file mode 100644 index 0000000000..eb674caba9 --- /dev/null +++ b/docs/docsite/rst/api/index.rst @@ -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 diff --git a/docs/docsite/rst/dev_guide/debugging.rst b/docs/docsite/rst/dev_guide/debugging.rst index a751354cd5..d0c903fa8c 100644 --- a/docs/docsite/rst/dev_guide/debugging.rst +++ b/docs/docsite/rst/dev_guide/debugging.rst @@ -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 :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 :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 - the python requests library is installed on the system before running the + your module includes `requests `_ then you'll have to make sure that + the python `requests library `_ is installed on the system before running 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 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 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 - different, however. ``excommunicate`` imports the :func:`main` + different, however. ``excommunicate`` imports the ``main`` function from the module and then calls that. This makes excommunicate 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 diff --git a/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst b/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst index 023ae5e09b..6414c1eb55 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst @@ -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. * 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 diff --git a/docs/docsite/rst/dev_guide/developing_python_3.rst b/docs/docsite/rst/dev_guide/developing_python_3.rst index 6d28d2c6a8..44c454aff0 100644 --- a/docs/docsite/rst/dev_guide/developing_python_3.rst +++ b/docs/docsite/rst/dev_guide/developing_python_3.rst @@ -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" (control codes). -In Python 2, the two types for these (:class:`str` for bytes and -:class:`unicode` for text) are often used interchangeably. When dealing only +In Python 2, the two types for these (:class:`str ` for bytes and +:func:`unicode ` for text) are often used interchangeably. When dealing only with ASCII characters, the strings can be combined, compared, and converted from one type to another automatically. When non-ASCII characters are introduced, Python 2 starts throwing exceptions due to not knowing what encoding the non-ASCII characters should be in. -Python 3 changes this behavior by making the separation between bytes (:class:`bytes`) -and text (:class:`str`) more strict. Python 3 will throw an exception when +Python 3 changes this behavior by making the separation between bytes (:class:`bytes `) +and text (:class:`str `) more strict. Python 3 will throw an exception when 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. @@ -95,7 +95,7 @@ Controller string strategy: the Unicode Sandwich ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 ` text type). For Unicode Sandwich we know that 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. 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. .. 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 all the types are the same (either all bytes or all text). Mixing 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`` makes all classes defined in the file into new-style -classes without explicitly inheriting from :class:`object`. +classes without explicitly inheriting from :class:`object `. 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 ` for the modules being 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 the importing, there's a new dot notation to do so. :division: Makes division of integers always return a float. If you need to 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 ` from a keyword into a function. .. seealso:: * `PEP 0328: Absolute Imports `_ diff --git a/docs/docsite/rst/dev_guide/testing/sanity/use-argspec-type-path.rst b/docs/docsite/rst/dev_guide/testing/sanity/use-argspec-type-path.rst index 7a77b2161e..3972b9eb14 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/use-argspec-type-path.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/use-argspec-type-path.rst @@ -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 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 ` 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 test. - -- cgit v1.2.1