From b0ec91e69e4cc578f0238ea7b60aeac91f2eedcd Mon Sep 17 00:00:00 2001 From: Toshio Kuratomi Date: Thu, 8 Aug 2019 11:56:07 -0700 Subject: [PATCH] Autointerpreter table (#60148) * Some framework for docs * Separate CSS file for our site-specific CSS. * Override the read-the-docs theme for tables so that tables don't always horizontally scroll * Add a |br| substitution that lets us line break inside of tables * Add |_| non-breaking-space substitution which is also for formatting tables * Configure rstcheck to ignore all substitutions which are being added by sphinx in the conf.py * Fix table of auto interpreter options The table was being hardcoded at a certain width to work around a read-the-docs theme bug. Fix the bug instead and format the table using better sphinx practices. * Remove unused substitutions We had substitutions defined that were never used in our documentation. Remove those. Also add to the rstcheck whitelist three substitutions which are defined by sphinx itself, version, release, and today. --- docs/docsite/_static/ansible.css | 16 ++++++ docs/docsite/rst/conf.py | 19 ++++--- .../rst/porting_guides/porting_guide_2.8.rst | 52 +++++++++---------- .../sanity/rstcheck/ignore-substitutions.txt | 5 +- 4 files changed, 55 insertions(+), 37 deletions(-) create mode 100644 docs/docsite/_static/ansible.css diff --git a/docs/docsite/_static/ansible.css b/docs/docsite/_static/ansible.css new file mode 100644 index 00000000000..3fea13034ad --- /dev/null +++ b/docs/docsite/_static/ansible.css @@ -0,0 +1,16 @@ +/* Fix for read the docs theme: + * https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html + */ +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} diff --git a/docs/docsite/rst/conf.py b/docs/docsite/rst/conf.py index 62f565eae44..c49108b1aa7 100644 --- a/docs/docsite/rst/conf.py +++ b/docs/docsite/rst/conf.py @@ -112,17 +112,14 @@ highlight_language = 'YAML+Jinja' # Substitutions, variables, entities, & shortcuts for text which do not need to link to anything. # For titles which should be a link, use the intersphinx anchors set at the index, chapter, and section levels, such as qi_start_: +# |br| is useful for formatting fields inside of tables +# |_| is a nonbreaking space; similarly useful inside of tables rst_epilog = """ -.. |acapi| replace:: *Ansible Core API Guide* -.. |acrn| replace:: *Ansible Core Release Notes* -.. |ac| replace:: Ansible Core -.. |acversion| replace:: Ansible Core Version 2.1 -.. |acversionshort| replace:: Ansible Core 2.1 -.. |versionshortest| replace:: 2.2 -.. |versiondev| replace:: 2.3 -.. |pubdate| replace:: July 19, 2016 -.. |rhel| replace:: Red Hat Enterprise Linux +.. |br| raw:: html +
+.. |_| unicode:: 0xA0 + :trim: """ @@ -148,7 +145,9 @@ html_context = { 'current_version': version, 'latest_version': '2.8', # list specifically out of order to make latest work - 'available_versions': ('latest', '2.7', '2.6', 'devel') + 'available_versions': ('latest', '2.7', '2.6', 'devel'), + 'css_files': ('_static/ansible.css', # overrides to the standard theme + ), } # The style sheet to use for HTML and HTML Help pages. A file of that name diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst index 17c4ab1e5ad..2829002bcc2 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst @@ -100,32 +100,32 @@ If you prefer to use the Python interpreter discovery behavior, use one of the four new values for ``ansible_python_interpreter`` introduced in Ansible 2.8: -+---------------------------+-----------------------------------------------+ -| New value | Behavior | -+===========================+===============================================+ -| | auto | | If a Python interpreter is discovered, | -| | (future default) | | Ansible uses the discovered Python, even if | -| | | | :command:`/usr/bin/python` is also present. | -| | | | Warns when using the fallback list. | -+---------------------------+-----------------------------------------------+ -| | **auto_legacy** | | If a Python interpreter is discovered, and | -| | (Ansible 2.8 default) | | :command:`/usr/bin/python` is absent, | -| | | | Ansible uses the discovered Python. Warns | -| | | | when using the fallback list. | -| | | | | -| | | | If a Python interpreter is discovered, and | -| | | | :command:`/usr/bin/python` is present, | -| | | | Ansible uses :command:`/usr/bin/python` and | -| | | | prints a deprecation warning about future | -| | | | default behavior. Warns when using the | -| | | | fallback list. | -+---------------------------+-----------------------------------------------+ -| | auto_legacy_silent | | Behaves like ``auto_legacy`` but suppresses | -| | | | the deprecation and fallback-list warnings. | -+---------------------------+-----------------------------------------------+ -| | auto_silent | | Behaves like ``auto`` but suppresses the | -| | | | fallback-list warning. | -+---------------------------+-----------------------------------------------+ ++---------------------------+---------------------------------------------+ +| New value | Behavior | ++===========================+=============================================+ +| auto |br| | If a Python interpreter is discovered, | +| (future default) | Ansible uses the discovered Python, even if | +| | :command:`/usr/bin/python` is also present. | +| | Warns when using the fallback list. | ++---------------------------+---------------------------------------------+ +| **auto_legacy** |br| | If a Python interpreter is discovered, and | +| (Ansible 2.8 default) | :command:`/usr/bin/python` is absent, | +| | Ansible uses the discovered Python. Warns | +| | when using the fallback list. | +| | | +| | If a Python interpreter is discovered, and | +| | :command:`/usr/bin/python` is present, | +| | Ansible uses :command:`/usr/bin/python` and | +| | prints a deprecation warning about future | +| | default behavior. Warns when using the | +| | fallback list. | ++---------------------------+---------------------------------------------+ +| auto_legacy_silent | Behaves like ``auto_legacy`` but suppresses | +| | the deprecation and fallback-list warnings. | ++---------------------------+---------------------------------------------+ +| auto_silent | Behaves like ``auto`` but suppresses the | +| | fallback-list warning. | ++---------------------------+---------------------------------------------+ In Ansible 2.12, Ansible will switch the default from :literal:`auto_legacy` to :literal:`auto`. diff --git a/test/lib/ansible_test/_data/sanity/rstcheck/ignore-substitutions.txt b/test/lib/ansible_test/_data/sanity/rstcheck/ignore-substitutions.txt index 393fcfb2f46..961e9bd9fd0 100644 --- a/test/lib/ansible_test/_data/sanity/rstcheck/ignore-substitutions.txt +++ b/test/lib/ansible_test/_data/sanity/rstcheck/ignore-substitutions.txt @@ -1,2 +1,5 @@ version -versiondev +release +today +br +_