From 46453c73ec3102578b06e321ad640ac928e6645c Mon Sep 17 00:00:00 2001 From: Luigi Toscano Date: Fri, 6 Sep 2019 16:46:14 +0200 Subject: [PATCH] Doc updates: bump theme to 1.20.0, add PDF build - bump the openstackdocstheme requirement to 1.20.0, the minimum recommended version nowadays, and clean the configuration by removing the options now provided by the theme; - add the pdf-docs tox environment according the established guidelines; - remove a useless extra title (for both builders); - docs tox environment: clean up only the generated html, not the entire build directory; - disable the too smart smartquotes option for the latex builder; - improve the title of the latex document. Story: 2006117 Task: 35493 Change-Id: I353e33db27c8d676398973995960b98d3163aa0d --- doc/requirements.txt | 2 +- doc/source/conf.py | 29 ++--------------------------- doc/source/index.rst | 5 +---- lower-constraints.txt | 2 +- releasenotes/source/conf.py | 13 ------------- tox.ini | 13 ++++++++++++- 6 files changed, 17 insertions(+), 47 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 608a0b3..b5107c6 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,7 +1,7 @@ # The order of packages is significant, because pip processes them in the order # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. -openstackdocstheme>=1.18.1 # Apache-2.0 +openstackdocstheme>=1.20.0 # Apache-2.0 os-api-ref>=1.4.0 # Apache-2.0 reno>=2.5.0 # Apache-2.0 sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD diff --git a/doc/source/conf.py b/doc/source/conf.py index 2ab52a3..833c88f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -18,7 +18,6 @@ extensions = [ repository_name = 'openstack/sahara-plugin-spark' bug_project = '1104' bug_tag = 'doc' -html_last_updated_fmt = '%Y-%m-%d %H:%M' openstack_projects = [ 'sahara' @@ -37,18 +36,8 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'sahara-plugin-spark' copyright = u'2015, Sahara team' -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.0.1' -# The full version, including alpha/beta/rc tags. -release = '0.0.1' - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None @@ -123,10 +112,6 @@ html_theme = 'openstackdocs' # using the given strftime format. #html_last_updated_fmt = '%b %d, %Y' -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -html_use_smartypants = False - # Custom sidebar templates, maps document names to template names. #html_sidebars = {} @@ -166,21 +151,10 @@ htmlhelp_basename = 'saharasparkplugin-testsdoc' # -- Options for LaTeX output -------------------------------------------------- -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'sahara-plugin-spark.tex', u'sahara-plugin-spark Documentation', + ('index', 'doc-sahara-plugin-spark.tex', u'Sahara Spark Plugin Documentation', u'Sahara team', 'manual'), ] @@ -204,6 +178,7 @@ latex_documents = [ # If false, no module index is generated. #latex_domain_indices = True +smartquotes_excludes = {'builders': ['latex']} # -- Options for manual page output -------------------------------------------- diff --git a/doc/source/index.rst b/doc/source/index.rst index f2b57b0..756a087 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,8 +1,5 @@ Spark plugin for Sahara -======================== - -User Guide ----------- +======================= .. toctree:: :maxdepth: 2 diff --git a/lower-constraints.txt b/lower-constraints.txt index 1d2ebcc..59ebb16 100644 --- a/lower-constraints.txt +++ b/lower-constraints.txt @@ -65,7 +65,7 @@ msgpack-python==0.5.6 munch==2.3.2 netaddr==0.7.19 netifaces==0.10.9 -openstackdocstheme==1.29.0 +openstackdocstheme==1.20.0 openstacksdk==0.24.0 os-api-ref==1.6.0 os-client-config==1.31.2 diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index 4d29c3d..1bf4ffd 100644 --- a/releasenotes/source/conf.py +++ b/releasenotes/source/conf.py @@ -23,7 +23,6 @@ extensions = [ repository_name = 'openstack/sahara-plugin-spark' bug_project = '1104' bug_tag = 'releasenotes' -html_last_updated_fmt = '%Y-%m-%d %H:%M' # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -35,7 +34,6 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'Sahara Spark Plugin Release Notes' copyright = u'2015, Sahara Developers' # Release do not need a version number in the title, they @@ -140,17 +138,6 @@ htmlhelp_basename = 'SaharaSparkReleaseNotesdoc' # -- Options for LaTeX output --------------------------------------------- -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # 'preamble': '', -} - # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). diff --git a/tox.ini b/tox.ini index 7de2109..2dd97d6 100644 --- a/tox.ini +++ b/tox.ini @@ -49,11 +49,22 @@ deps = -c{env:UPPER_CONSTRAINTS_FILE:https://opendev.org/openstack/requirements/raw/branch/master/upper-constraints.txt} -r{toxinidir}/doc/requirements.txt commands = - rm -rf doc/html doc/build + rm -rf doc/build/html sphinx-build -W -b html doc/source doc/build/html whitelist_externals = rm +[testenv:pdf-docs] +basepython = python3 +deps = {[testenv:docs]deps} +commands = + rm -rf doc/build/pdf + sphinx-build -W -b latex doc/source doc/build/pdf + make -C doc/build/pdf +whitelist_externals = + make + rm + [testenv:releasenotes] basepython = python3 deps =