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

214 lines
7.7 KiB
Makefile
Raw Normal View History

leaving os immediate
2017-01-20 05:11:53 +01:00
OS := $(shell uname -s)
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-18 03:55:03 +01:00
SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"):
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 22:07:35 +02:00
PLUGIN_FORMATTER=../../hacking/build-ansible.py docs-build
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 15:24:45 +02:00
TESTING_FORMATTER=../bin/testing_formatter.sh
Move common build code from _build_helpers (#55986) We have some common code used by several docs scripts. Migrate that into the build-only shared code repository. * Move lib/ansible/utils/_build_helpers.py to the directory for common build code * Migrate docs/bin/dump_config.py to a build-ansible subcommand * Migrate dump_keywords to the build-ansible framework * Make the script more maintainable by using functions and good variable names * Port to Python3 idioms * Fix bug so that private attributes will be undocumented * Move generate_man to a build-ansible subcommand * Port plugin_formatter to a build-ansible subcommand * Rework command_plugins so that docs scripts can target Python-3.4+ and releng-only subcommands can use more recent versions of Python. The architecture is now that command_plugins/* need to be importable on Python-3.4. The init_parsers() method needs to run on Python-3.4. But the main() method can utilize features of more recent Python as long as it fits within those parameters. * Update docs build requirements Port the plugin_formatter to build-ansible framework
2019-07-16 21:19:01 +02:00
KEYWORD_DUMPER=../../hacking/build-ansible.py document-keywords
CONFIG_DUMPER=../../hacking/build-ansible.py document-config
GENERATE_CLI=../../hacking/build-ansible.py generate-man
Generate galaxy.yml based on single source of truth (#59170) * Generate galaxy.yml based on single source of truth * Fix up tests and align file names * Minor Makefile tweak * Remove link in galaxy.yml file and make it a template file * Moved collections docs to dev_guide * change Makefile clean path * Added readme to example meta file * review fixes * Use newer style for doc generation script * Fix mistake in dev_guide index * removed uneeded file, fixed links and added preview banner * Moved banner for sanity test
2019-07-22 22:50:46 +02:00
COLLECTION_DUMPER=../../hacking/build-ansible.py collection-meta
Need to define the OS variable at this level too
2017-01-20 04:50:29 +01:00
ifeq ($(shell echo $(OS) | egrep -ic 'Darwin|FreeBSD|OpenBSD|DragonFly'),1)
set cpus only if not set already
2017-01-20 05:09:55 +01:00
CPUS ?= $(shell sysctl hw.ncpu|awk '{print $$2}')
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 20:38:02 +01:00
else
set cpus only if not set already
2017-01-20 05:09:55 +01:00
CPUS ?= $(shell nproc)
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 20:38:02 +01:00
endif
Subtree merge of ansible-docs
2012-10-08 13:44:38 +02:00
Documentation: Lay the ground for i18n work. (#73746) * Documentation: Lay the ground for i18n work. * Translating both ansible-core and ansible docs requires msgcat (a program from the gettext package). If msgcat is not present, only the ansible-core index file's strings will be extracted for translation. If this is a problem, a short hacking script could be written to take the place of msgcat (merging the various index pot files into a single pot file). Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-03-05 18:31:56 +01:00
# Intenationalisation and Localisation
LANGUAGES ?=
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 22:07:35 +02:00
# Sets the build output directory for the main docsite if it's not already specified
Adds the ability to override the doc build output directory from the command line. (#36604) * Adds the ability to override the doc build output from the command line. * For safety, removed straight rm of BUILDDIR and removed subdirectories instead. * Added check to see if BUILDDIR was defined to main makefile
2018-03-01 01:01:18 +01:00
ifndef BUILDDIR
BUILDDIR = _build
endif
Documentation: Lay the ground for i18n work. (#73746) * Documentation: Lay the ground for i18n work. * Translating both ansible-core and ansible docs requires msgcat (a program from the gettext package). If msgcat is not present, only the ansible-core index file's strings will be extracted for translation. If this is a problem, a short hacking script could be written to take the place of msgcat (merging the various index pot files into a single pot file). Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-03-05 18:31:56 +01:00
ifndef POTDIR
POTDIR = $(BUILDDIR)/gettext
endif
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 22:07:35 +02:00
# Backwards compat for separate VARS
PLUGIN_ARGS=
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 17:14:27 +02:00
ifdef MODULES
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 22:07:35 +02:00
ifndef PLUGINS
PLUGIN_ARGS = -l $(MODULES)
else
PLUGIN_ARGS = -l $(MODULES),$(PLUGINS)
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 17:14:27 +02:00
endif
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 22:07:35 +02:00
else
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 17:14:27 +02:00
ifdef PLUGINS
PLUGIN_ARGS = -l $(PLUGINS)
endif
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 22:07:35 +02:00
endif
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
ANSIBLE_VERSION_ARGS=
ifdef ANSIBLE_VERSION
ANSIBLE_VERSION_ARGS=--ansible-version=$(ANSIBLE_VERSION)
endif
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 17:14:27 +02:00
Fix netconf plugin related to collections (#65718) * Fix netconf plugin related to collections Fixes #65655 (partly) * Make netconf plugins configurable so that the information of ncclient device handler for give platform resides in the platform specific netconf plugin. * If the device handler value in ncclient is different from the ansible_network_os value the right value of `ncclient_device_handler` should be set in the plugin documentation. * Fix review comments * Fix CI issue * Fix review comment
2019-12-20 07:55:59 +01:00
DOC_PLUGINS ?= become cache callback cliconf connection httpapi inventory lookup netconf shell strategy vars
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-23 05:19:50 +02:00
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 22:07:35 +02:00
PYTHON=python
# fetch version from project release.py as single source-of-truth
VERSION := $(shell $(PYTHON) ../../packaging/release/versionhelper/version_helper.py --raw || echo error)
ifeq ($(findstring error,$(VERSION)), error)
$(error "version_helper failed")
endif
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
MAJOR_VERSION := $(shell $(PYTHON) ../../packaging/release/versionhelper/version_helper.py --majorversion || echo error)
ifeq ($(findstring error,$(MAJOR_VERSION)), error)
$(error "version_helper failed to determine major version")
endif
add Makefile target for single HTML page (#25313)
2017-06-02 20:11:28 +02:00
assertrst:
ifndef rst
$(error specify document or pattern with rst=somefile.rst)
endif
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-18 03:55:03 +01:00
all: docs
Subtree merge of ansible-docs
2012-10-08 13:44:38 +02:00
Docs: Make docsite rebuilds smarter/faster (#45062) * Make the following scripts idempotent so that we only have to rebuild changed docs, not all docs: * plugin_formatter * generate_man * dump_keywords.py * dump_config.py * testing_formatter.sh
2018-09-12 22:50:36 +02:00
docs: htmldocs
Add the start of a graphviz doc to illustrate variable precedence graphically.
2014-05-09 23:13:01 +02:00
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
coredocs: core_htmldocs
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 22:07:35 +02:00
generate_rst: collections_meta config cli keywords plugins testing
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
core_generate_rst: collections_meta config cli keywords base_plugins testing
Documentation: Lay the ground for i18n work. (#73746) * Documentation: Lay the ground for i18n work. * Translating both ansible-core and ansible docs requires msgcat (a program from the gettext package). If msgcat is not present, only the ansible-core index file's strings will be extracted for translation. If this is a problem, a short hacking script could be written to take the place of msgcat (merging the various index pot files into a single pot file). Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-03-05 18:31:56 +01:00
# At the moment localizing the plugins and collections is not required for the ongoing
# localisation effort. It will come at a later time.
gettext_generate_rst: collections_meta config cli keywords testing
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
# The following two symlinks are necessary to produce two different docsets
# from the same set of rst files (Ansible the package docs, and core docs).
# Symlink the relevant index into place for building Ansible docs
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
ansible_structure:
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
# We must have python and python-packaging for the version_helper
# script so use it for version comparison
if python -c "import sys, packaging.version as p; sys.exit(not p.Version('$(MAJOR_VERSION)') > p.Version('2.10'))" ; then \
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
echo "Creating symlinks in ansible_structure"; \
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
ln -sf ../rst/ansible_index.rst rst/index.rst; \
ln -sf ../sphinx_conf/ansible_conf.py rst/conf.py; \
else \
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
echo 'Creating symlinks for older ansible in ansible_structure'; \
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
ln -sf ../rst/2.10_index.rst rst/index.rst; \
ln -sf ../sphinx_conf/2.10_conf.py rst/conf.py; \
fi
# Symlink the relevant index into place for building core docs
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
core_structure:
@echo "Creating symlinks in core_structure"
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
-ln -sf ../rst/core_index.rst rst/index.rst
-ln -sf ../sphinx_conf/core_conf.py rst/conf.py
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 https://github.com/alikins/ansible/commit/6e34ea62429c417939bd96b6de5bf7e6ab1ff765 and https://github.com/alikins/ansible/commit/a3afc785357878da354e21a709cf3b9f16c3f146 * 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 21:44:20 +02:00
Documentation: Lay the ground for i18n work. (#73746) * Documentation: Lay the ground for i18n work. * Translating both ansible-core and ansible docs requires msgcat (a program from the gettext package). If msgcat is not present, only the ansible-core index file's strings will be extracted for translation. If this is a problem, a short hacking script could be written to take the place of msgcat (merging the various index pot files into a single pot file). Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-03-05 18:31:56 +01:00
# Symlink the relevant index into place for building core docs
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
gettext_structure:
@echo "Creating symlinks in gettext_structure"
Documentation: Lay the ground for i18n work. (#73746) * Documentation: Lay the ground for i18n work. * Translating both ansible-core and ansible docs requires msgcat (a program from the gettext package). If msgcat is not present, only the ansible-core index file's strings will be extracted for translation. If this is a problem, a short hacking script could be written to take the place of msgcat (merging the various index pot files into a single pot file). Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-03-05 18:31:56 +01:00
-ln -sf ../rst/core_index.rst rst/index.rst
-ln -sf ../sphinx_conf/all_conf.py rst/conf.py
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
gettext: gettext_structure gettext_generate_rst
Documentation: Lay the ground for i18n work. (#73746) * Documentation: Lay the ground for i18n work. * Translating both ansible-core and ansible docs requires msgcat (a program from the gettext package). If msgcat is not present, only the ansible-core index file's strings will be extracted for translation. If this is a problem, a short hacking script could be written to take the place of msgcat (merging the various index pot files into a single pot file). Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-03-05 18:31:56 +01:00
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx gettext
# if msgcat is installed handle all indexes, otherwise use the index from gettext_structure.
-msgcat "$(POTDIR)/core_index.pot" "$(POTDIR)/ansible_index.pot" "$(POTDIR)/2.10_index.pot" > "$(POTDIR)/tmp_index.pot" && mv "$(POTDIR)/tmp_index.pot" "$(POTDIR)/index.pot"
rm "$(POTDIR)/core_index.pot" "$(POTDIR)/ansible_index.pot" "$(POTDIR)/2.10_index.pot"
generate-po:
ifeq ($(LANGUAGES),)
@echo 'LANGUAGES is not defined. It is mandatory. LANGUAGES should be a comma separated list of languages to support. (Exampe: fr,es)'
else
(cd docs/docsite/; sphinx-intl update -w 0 -d rst/locales -p "$(POTDIR)" -l $(LANGUAGES))
endif
needs-translation:
ifeq ($(LANGUAGES),)
@echo 'LANGUAGES is not defined. It is mandatory. LANGUAGES should be a comma separated list of languages to support. (Exampe: fr,es)'
else
(cd docs/docsite/; sphinx-intl stat -d rst/locales -l $(LANGUAGES) | grep -E ' [1-9][0-9]* (fuzzy|untranslated)' | sort)
endif
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
htmldocs: ansible_structure generate_rst
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 20:32:27 +01:00
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html
Subtree merge of ansible-docs
2012-10-08 13:44:38 +02:00
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
core_htmldocs: core_structure core_generate_rst
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 22:07:35 +02:00
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx html
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
singlehtmldocs: ansible_structure generate_rst
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 22:45:05 +02:00
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
core_singlehtmldocs: core_structure core_generate_rst
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 22:07:35 +02:00
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx singlehtml
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
# Note: The linkcheckdocs and htmlsingle targets depend on gettext_structure
# because that one does not exclude any rst files in its conf.py.
linkcheckdocs: gettext_structure generate_rst
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx linkcheck
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 22:07:35 +02:00
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
htmlsingle: assertrst gettext_structure
sphinx-build -j $(CPUS) -b html -d $(BUILDDIR)/doctrees ./rst $(BUILDDIR)/html rst/$(rst)
@echo "Output is in $(BUILDDIR)/html/$(rst:.rst=.html)"
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-18 03:55:03 +01:00
webdocs: docs
add webdocs as alias
2016-01-25 16:33:50 +01:00
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-18 03:55:03 +01:00
#TODO: leaving htmlout removal for those having older versions, should eventually be removed also
Subtree merge of ansible-docs
2012-10-08 13:44:38 +02:00
clean:
Adds the ability to override the doc build output directory from the command line. (#36604) * Adds the ability to override the doc build output from the command line. * For safety, removed straight rm of BUILDDIR and removed subdirectories instead. * Added check to see if BUILDDIR was defined to main makefile
2018-03-01 01:01:18 +01:00
@echo "Cleaning $(BUILDDIR)"
-rm -rf $(BUILDDIR)/doctrees
-rm -rf $(BUILDDIR)/html
Merge
2013-06-09 19:55:58 +02:00
-rm -rf htmlout
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 10:47:39 +01:00
-rm -rf module_docs
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 22:07:35 +02:00
-rm -rf $(BUILDDIR)
Subtree merge of ansible-docs
2012-10-08 13:44:38 +02:00
-rm -f .buildinfo
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-10 20:01:10 +02:00
-rm -f objects.inv
Subtree merge of ansible-docs
2012-10-08 13:44:38 +02:00
-rm -rf *.doctrees
Add staticmin make target for compressing docs related css and js files, currently only theme.css
2014-01-03 02:35:29 +01:00
@echo "Cleaning up minified css files"
find . -type f -name "*.min.css" -delete
Subtree merge of ansible-docs
2012-10-08 13:44:38 +02:00
@echo "Cleaning up byte compiled python stuff"
find . -regex ".*\.py[co]$$" -delete
@echo "Cleaning up editor backup files"
find . -type f \( -name "*~" -or -name "#*" \) -delete
find . -type f \( -name "*.swp" \) -delete
Much rejoicing, ansibleworks.com is now ansible.com Also note AWX is named "Tower" now, as we found that simpler.
2014-01-28 17:04:34 +01:00
@echo "Cleaning up generated rst"
removes docs/api dir from .gitignore and Makefile (#47366) * removes docs/api dir from .gitignore and Makefile * reduces noise on removing build artifacts
2018-10-19 23:06:15 +02:00
rm -f rst/playbooks_directives.rst
rm -f rst/reference_appendices/config.rst
rm -f rst/reference_appendices/playbooks_keywords.rst
Generate galaxy.yml based on single source of truth (#59170) * Generate galaxy.yml based on single source of truth * Fix up tests and align file names * Minor Makefile tweak * Remove link in galaxy.yml file and make it a template file * Moved collections docs to dev_guide * change Makefile clean path * Added readme to example meta file * review fixes * Use newer style for doc generation script * Fix mistake in dev_guide index * removed uneeded file, fixed links and added preview banner * Moved banner for sanity test
2019-07-22 22:50:46 +02:00
rm -f rst/dev_guide/collections_galaxy_meta.rst
Install ansible-test (#60718) * Install ansible-test Modify the install script to install ansible-test and its supporting code. Alternative to #60701 that doesn't change package_dir ansible for fear that it might regress https://github.com/ansible/ansible/issues/10437 Also: * No longer use package_data. Everything in the package dirs is going to be installed. Anything that shouldn't be installed needs to be moved elsewhere. * modify the algorithm to store symlinks which are in the same tree instead of same directory * Add ansible_test files to package-data sanity test * MANIFEST.in cleanups * Add lib/ansible/config/*.yml * Make most things in code directories (lib/ansible and test/lib/ansible_test/) use explicit file extensions instead of wildcards for maintainability * Exclude common file extensions that we don't want included in the code directories * Change package-data test to be more complete * Now compares the repository, sdist, and install * Compares both that everything in the sdist is in the repo and everything in the install is in the sdist in addition to comparing that everything in the repo that we want is in the install * Leave out test artifacts Only include the directory structure for test/results and test/cache not any files that may have been generated by test runs Remove test/utils files from the sdist as these are only needed for our CI cleanup of docs in MANIFEST.in; getting rid of build files. * Add the ability to output sdist and snapshot to specific directory * Add a warning about modifying the heuristic to setup.py * Address generated files * Use make snapshot instead of sdist to generate changelog and man pages and make sure they're included * Ignore both the test/utils and generated test files (results, cache) * Deal with Python3 __pycache__ byte code caches * Don't check documentation, that isn't built for the sdist * Restructure for clarity * Add cli web docs to make clean This was causing problems when attempting to test that the sdist didn't have extra files * Fix bug constructing python names from __pycache__ names * Create a clean repo to work from * Exclude test/legacy and be more explicit on extensions * Exclude the legacy directory from sdist
2019-08-21 08:53:35 +02:00
rm -f rst/cli/*.rst
Add link to all module and plugin indexes (#72743) * Add link to all module and plugin indexes. * Use glob setting for toctree. * Explicitly include new file. * Move all_plugins one level up. * Revert "Move all_plugins one level up." This reverts commit bd47e82eadbf18b1f4736c62fde47f6e15191723. * Revert "Explicitly include new file." This reverts commit 74ae50a734d7ca6c904f3fdc91b71aa8bd7e5b4a. * Adjust .gitignore * Revert "Revert "Explicitly include new file."" This reverts commit f30d99c861b65f1968c402abdad6ff93c15d68b8. * Fix docs make clean Now that there's a static file in rst/collections, we have to be more explicit about how we clean the generated files out of that directory. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2020-12-18 17:55:31 +01:00
for filename in `ls rst/collections/` ; do \
if test x"$$filename" != x'all_plugins.rst' ; then \
rm -rf "rst/collections/$$filename"; \
fi \
done
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
@echo "Cleanning up generated ansible_structure"
Update docs on working on docs (#74201) * Fix the Makefile's htmlsingle command. Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
2021-04-21 21:15:27 +02:00
find . -type l -delete
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 22:07:35 +02:00
@echo "Cleaning up legacy generated rst locations"
rm -rf rst/modules
rm -f rst/plugins/*/*.rst
Subtree merge of ansible-docs
2012-10-08 13:44:38 +02:00
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 19:52:13 +01:00
.PHONY: docs clean
Subtree merge of ansible-docs
2012-10-08 13:44:38 +02:00
Generate galaxy.yml based on single source of truth (#59170) * Generate galaxy.yml based on single source of truth * Fix up tests and align file names * Minor Makefile tweak * Remove link in galaxy.yml file and make it a template file * Moved collections docs to dev_guide * change Makefile clean path * Added readme to example meta file * review fixes * Use newer style for doc generation script * Fix mistake in dev_guide index * removed uneeded file, fixed links and added preview banner * Moved banner for sanity test
2019-07-22 22:50:46 +02:00
collections_meta: ../templates/collections_galaxy_meta.rst.j2
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 22:07:35 +02:00
$(COLLECTION_DUMPER) --template-file=../templates/collections_galaxy_meta.rst.j2 --output-dir=rst/dev_guide/ ../../lib/ansible/galaxy/data/collections_galaxy_meta.yml
Generate galaxy.yml based on single source of truth (#59170) * Generate galaxy.yml based on single source of truth * Fix up tests and align file names * Minor Makefile tweak * Remove link in galaxy.yml file and make it a template file * Moved collections docs to dev_guide * change Makefile clean path * Added readme to example meta file * review fixes * Use newer style for doc generation script * Fix mistake in dev_guide index * removed uneeded file, fixed links and added preview banner * Moved banner for sanity test
2019-07-22 22:50:46 +02:00
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 https://github.com/alikins/ansible/commit/6e34ea62429c417939bd96b6de5bf7e6ab1ff765 and https://github.com/alikins/ansible/commit/a3afc785357878da354e21a709cf3b9f16c3f146 * 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 21:44:20 +02:00
# TODO: make generate_man output dir cli option
Move common build code from _build_helpers (#55986) We have some common code used by several docs scripts. Migrate that into the build-only shared code repository. * Move lib/ansible/utils/_build_helpers.py to the directory for common build code * Migrate docs/bin/dump_config.py to a build-ansible subcommand * Migrate dump_keywords to the build-ansible framework * Make the script more maintainable by using functions and good variable names * Port to Python3 idioms * Fix bug so that private attributes will be undocumented * Move generate_man to a build-ansible subcommand * Port plugin_formatter to a build-ansible subcommand * Rework command_plugins so that docs scripts can target Python-3.4+ and releng-only subcommands can use more recent versions of Python. The architecture is now that command_plugins/* need to be importable on Python-3.4. The init_parsers() method needs to run on Python-3.4. But the main() method can utilize features of more recent Python as long as it fits within those parameters. * Update docs build requirements Port the plugin_formatter to build-ansible framework
2019-07-16 21:19:01 +02:00
cli:
ensure cli dir exists before saving files to it
2018-02-13 23:43:26 +01:00
mkdir -p rst/cli
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 22:07:35 +02:00
$(GENERATE_CLI) --template-file=../templates/cli_rst.j2 --output-dir=rst/cli/ --output-format rst ../../lib/ansible/cli/*.py
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 https://github.com/alikins/ansible/commit/6e34ea62429c417939bd96b6de5bf7e6ab1ff765 and https://github.com/alikins/ansible/commit/a3afc785357878da354e21a709cf3b9f16c3f146 * 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 21:44:20 +02:00
Move common build code from _build_helpers (#55986) We have some common code used by several docs scripts. Migrate that into the build-only shared code repository. * Move lib/ansible/utils/_build_helpers.py to the directory for common build code * Migrate docs/bin/dump_config.py to a build-ansible subcommand * Migrate dump_keywords to the build-ansible framework * Make the script more maintainable by using functions and good variable names * Port to Python3 idioms * Fix bug so that private attributes will be undocumented * Move generate_man to a build-ansible subcommand * Port plugin_formatter to a build-ansible subcommand * Rework command_plugins so that docs scripts can target Python-3.4+ and releng-only subcommands can use more recent versions of Python. The architecture is now that command_plugins/* need to be importable on Python-3.4. The init_parsers() method needs to run on Python-3.4. But the main() method can utilize features of more recent Python as long as it fits within those parameters. * Update docs build requirements Port the plugin_formatter to build-ansible framework
2019-07-16 21:19:01 +02:00
keywords: ../templates/playbooks_keywords.rst.j2
show keyword documentation in ansible-doc (#72476) * show keyword documentation in ansible-doc Co-authored-by: Felix Fontein <felix@fontein.de>
2020-11-09 15:55:17 +01:00
$(KEYWORD_DUMPER) --template-dir=../templates --output-dir=rst/reference_appendices/ ../../lib/ansible/keyword_desc.yml
now generate list of playbook ojbect directives TODO: needs links/info and conditionals added
2016-02-25 22:41:50 +01:00
Move common build code from _build_helpers (#55986) We have some common code used by several docs scripts. Migrate that into the build-only shared code repository. * Move lib/ansible/utils/_build_helpers.py to the directory for common build code * Migrate docs/bin/dump_config.py to a build-ansible subcommand * Migrate dump_keywords to the build-ansible framework * Make the script more maintainable by using functions and good variable names * Port to Python3 idioms * Fix bug so that private attributes will be undocumented * Move generate_man to a build-ansible subcommand * Port plugin_formatter to a build-ansible subcommand * Rework command_plugins so that docs scripts can target Python-3.4+ and releng-only subcommands can use more recent versions of Python. The architecture is now that command_plugins/* need to be importable on Python-3.4. The init_parsers() method needs to run on Python-3.4. But the main() method can utilize features of more recent Python as long as it fits within those parameters. * Update docs build requirements Port the plugin_formatter to build-ansible framework
2019-07-16 21:19:01 +02:00
config: ../templates/config.rst.j2
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 22:07:35 +02:00
$(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ ../../lib/ansible/config/base.yml
# For now, if we're building on devel, just build base docs. In the future we'll want to build docs that
# are the latest versions on galaxy (using a different antsibull-docs subcommand)
plugins:
Split Ansible docs from core docs (#73616) * excludes scenario guides from core docs, splits porting guides and roadmaps, symlinks indices to create index.html pages, and adds .gitignore entries for conf.py and the toplevel index.rst files generated by the docs build This solution builds three types of docs: * ansible-2.10 and earlier: all the docs. Handle this via `make webdocs ANSIBLE_VERSION=2.10` * ansible-3 and later: a subset of the docs for the ansible package. Handle this via `make webdocs ANSIBLE_VERSION=3` (change the ANSIBLE_VERSION to match the version being built for. * ansible-core: a subset of the docs for the ansible-core package. Handle this via `make coredocs`. * `make webdocs` now always builds all the collection docs * Use `make coredocs` to limit it to core plugins only * The user specifies the desired version. If no ANSIBLE_VERSION is specified, build plugins for the latest release of ansible Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Matt Clay <matt@mystile.com>
2021-02-17 16:57:05 +01:00
$(PLUGIN_FORMATTER) full -o rst $(ANSIBLE_VERSION_ARGS) $(PLUGIN_ARGS);\
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 22:07:35 +02:00
Rebased pr73824 (#73934) Co-authored-by: Eugene <k.evgen61@gmail.com> Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com>
2021-03-17 21:07:38 +01:00
# This only builds the plugin docs included with ansible-core
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 22:07:35 +02:00
base_plugins:
$(PLUGIN_FORMATTER) base -o rst $(PLUGIN_ARGS);\
Subtree merge of ansible-docs
2012-10-08 13:44:38 +02:00
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 15:24:45 +02:00
testing:
$(TESTING_FORMATTER)
added epub entry for makefile
2017-05-01 19:40:49 +02:00
epub:
Use $(MAKE) instead of raw "make" (#39588) This Makefile uses non-standard constructs. As such it can only be parsed by GNU make, which is often installed as 'gmake' instead of 'make'. Using $(MAKE) ensures the same version of make gets called that is used to execute the top level.
2018-05-25 05:30:14 +02:00
(CPUS=$(CPUS) $(MAKE) -f Makefile.sphinx epub)
Reference in a new issue Copy permalink