diff --git a/doc/source/conf.py b/doc/source/conf.py index bf91c795..8512a052 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -66,7 +66,7 @@ html_theme = 'openstackdocs' # So that we can enable "log-a-bug" links from each output HTML page, this # variable must be set to a format that includes year, month, day, hours and # minutes. -html_last_updated_fmt = '%Y-%m-%d %H:%M' +# html_last_updated_fmt = '%Y-%m-%d %H:%M' # Output file base name for HTML help builder. htmlhelp_basename = '%sdoc' % project diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 8c21ad67..c2e92506 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -4,13 +4,13 @@ Installation At the command line: - .. code-block:: console +.. code-block:: console - $ pip install openstack-doc-tools + $ pip install openstack-doc-tools Or, if you have virtualenvwrapper installed: - .. code-block:: console +.. code-block:: console - $ mkvirtualenv openstack-doc-tools - $ pip install openstack-doc-tools + $ mkvirtualenv openstack-doc-tools + $ pip install openstack-doc-tools diff --git a/doc/source/man/openstack-doc-test.rst b/doc/source/man/openstack-doc-test.rst index fe69b324..f596be2f 100644 --- a/doc/source/man/openstack-doc-test.rst +++ b/doc/source/man/openstack-doc-test.rst @@ -2,9 +2,9 @@ openstack-doc-test ================== ------------------------------------------------------- +------------------------- OpenStack Validation tool ------------------------------------------------------- +------------------------- SYNOPSIS ======== @@ -20,77 +20,77 @@ documentation content. OPTIONS ======= - **General options** +**General options** - **--api-site** - Special handling for api-site and other API repositories - to handle WADL. +**--api-site** + Special handling for api-site and other API repositories + to handle WADL. - **--build-file-exception BUILD_FILE_EXCEPTION** - File that will be skipped during delete and build checks to - generate dependencies. This should be done for invalid XML files - only. +**--build-file-exception BUILD_FILE_EXCEPTION** + File that will be skipped during delete and build checks to + generate dependencies. This should be done for invalid XML files + only. - **--check-build** - Try to build books using modified files. +**--check-build** + Try to build books using modified files. - **--check-deletions** - Check that deleted files are not used. +**--check-deletions** + Check that deleted files are not used. - **--check-links** - Check that linked URLs are valid and reachable. +**--check-links** + Check that linked URLs are valid and reachable. - **--check-niceness** - Check the niceness of files, for example whitespace. +**--check-niceness** + Check the niceness of files, for example whitespace. - **--check-syntax** - Check the syntax of modified files. +**--check-syntax** + Check the syntax of modified files. - **--check-all** - Run all checks (default if no arguments are given). +**--check-all** + Run all checks (default if no arguments are given). - **--config-file PATH** - Path to a config file to use. Multiple config files can be - specified, with values in later files taking precedence. +**--config-file PATH** + Path to a config file to use. Multiple config files can be + specified, with values in later files taking precedence. - **--debug** - Enable debug code. +**--debug** + Enable debug code. - **--file-exception FILE_EXCEPTION** - File that will be skipped during niceness and syntax validation. +**--file-exception FILE_EXCEPTION** + File that will be skipped during niceness and syntax validation. - **--force** - Force the validation of all files and build all books. +**--force** + Force the validation of all files and build all books. - **-h, --help** - Show help message and exit. +**-h, --help** + Show help message and exit. - **--ignore-dir IGNORE_DIR** - Directory to ignore for building of manuals. The parameter can - be passed multiple times to add several directories. +**--ignore-dir IGNORE_DIR** + Directory to ignore for building of manuals. The parameter can + be passed multiple times to add several directories. - **--language LANGUAGE, -l LANGUAGE** - Build translated manual for language in path generate/$LANGUAGE . +**--language LANGUAGE, -l LANGUAGE** + Build translated manual for language in path generate/$LANGUAGE . - **--only-book ONLY_BOOK** - Build each specified manual. +**--only-book ONLY_BOOK** + Build each specified manual. - **--parallel** - Build books in parallel (default). +**--parallel** + Build books in parallel (default). - **--print-unused-files** - Print list of files that are not included anywhere as part of - check-build. +**--print-unused-files** + Print list of files that are not included anywhere as part of + check-build. - **--publish** - Setup content in publish-docs directory for publishing to - external website. +**--publish** + Setup content in publish-docs directory for publishing to + external website. - **--verbose** - Verbose execution. +**--verbose** + Verbose execution. - **--version** - Output version number. +**--version** + Output version number. FILES ===== diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 61126a51..e1615499 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -4,6 +4,6 @@ Usage To use openstack-doc-tools in a project: - .. code-block:: python +.. code-block:: python - import os_doc_tools + import os_doc_tools diff --git a/lower-constraints.txt b/lower-constraints.txt index 5e2cfea6..b8998e1d 100644 --- a/lower-constraints.txt +++ b/lower-constraints.txt @@ -21,7 +21,7 @@ lxml==3.4.1 MarkupSafe==1.0 mccabe==0.2.1 mock==2.0.0 -openstackdocstheme==1.18.1 +openstackdocstheme==1.20.0 pbr==2.0.0 pep8==1.5.7 pyflakes==0.8.1 diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index cc29474d..557a6da6 100644 --- a/releasenotes/source/conf.py +++ b/releasenotes/source/conf.py @@ -145,7 +145,7 @@ html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. # html_last_updated_fmt = '%b %d, %Y' -html_last_updated_fmt = '%Y-%m-%d %H:%M' +# html_last_updated_fmt = '%Y-%m-%d %H:%M' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. @@ -190,17 +190,6 @@ htmlhelp_basename = 'OpenStack-Doc-Tools-ReleaseNotesdoc' # -- 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/requirements.txt b/requirements.txt index 8a10a6b2..0b5f646f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,6 +6,7 @@ pbr!=2.1.0,>=2.0.0 # Apache-2.0 iso8601>=0.1.11 # MIT lxml!=3.7.0,>=3.4.1 # BSD docutils>=0.11 # OSI-Approved Open Source, Public Domain -sphinx!=1.6.6,!=1.6.7,>=1.6.5 # BSD +sphinx>=1.6.5,!=1.6.6,!=1.6.7,<2.0.0;python_version=='2.7' # BSD +sphinx>=1.6.5,!=1.6.6,!=1.6.7,!=2.1.0;python_version>='3.4' # BSD demjson>=2.2.2 # GLGPLv3+ PyYAML>=3.12 # MIT diff --git a/setup.cfg b/setup.cfg index 839fd7a2..ceff14df 100644 --- a/setup.cfg +++ b/setup.cfg @@ -37,13 +37,5 @@ console_scripts = openstack-jsoncheck = os_doc_tools.jsoncheck:main openstack-indexpage = os_doc_tools.index:main -[build_sphinx] -source-dir = doc/source -build-dir = doc/build -all_files = 1 - -[upload_sphinx] -upload-dir = doc/build/html - [wheel] universal = 1 diff --git a/sitemap/README.rst b/sitemap/README.rst index 7196b3d9..f9a183da 100644 --- a/sitemap/README.rst +++ b/sitemap/README.rst @@ -47,35 +47,32 @@ Options ~~~~~~~ domain=URL + Sets the ``domain`` to crawl. Default is ``docs.openstack.org``. - Sets the ``domain`` to crawl. Default is ``docs.openstack.org``. + For example, to crawl https://developer.openstack.org use the following + command: - For example, to crawl https://developer.openstack.org use the following - command: + .. code-block:: console - .. code-block:: console + $ scrapy crawl sitemap -a domain=developer.openstack.org - $ scrapy crawl sitemap -a domain=developer.openstack.org - - The result is available in the ``sitemap_developer.openstack.org.xml`` file. + The result is available in the ``sitemap_developer.openstack.org.xml`` file. urls=URL + You can define a set of additional start URLs using the ``urls`` attribute. + Separate multiple URLs with ``,``. - You can define a set of additional start URLs using the ``urls`` attribute. - Separate multiple URLs with ``,``. + For example: - For example: + .. code-block:: console - .. code-block:: console - - $ scrapy crawl sitemap -a domain=developer.openstack.org -a urls="https://developer.openstack.org/de/api-guide/quick-start/" + $ scrapy crawl sitemap -a domain=developer.openstack.org -a urls="https://developer.openstack.org/de/api-guide/quick-start/" LOG_FILE=FILE + Write log messages to the specified file. - Write log messages to the specified file. + For example, to write to ``scrapy.log``: - For example, to write to ``scrapy.log``: + .. code-block:: console - .. code-block:: console - - $ scrapy crawl sitemap -s LOG_FILE=scrapy.log + $ scrapy crawl sitemap -s LOG_FILE=scrapy.log diff --git a/test-requirements.txt b/test-requirements.txt index 29b9a855..e31827f1 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -11,7 +11,7 @@ doc8>=0.6.0 # Apache-2.0 pylint==1.7.1 # GPLv2 reno>=2.5.0 # Apache-2.0 -openstackdocstheme>=1.18.1 # Apache-2.0 +openstackdocstheme>=1.20.0 # Apache-2.0 stestr>=2.0.0 # Apache-2.0 # mock object framework diff --git a/tox.ini b/tox.ini index 76fe2f1d..1c41107d 100644 --- a/tox.ini +++ b/tox.ini @@ -24,7 +24,7 @@ commands = doc8 -e txt -e rst doc/source/ HACKING.rst # Run bashate during pep8 runs to ensure violations are caught by # the check and gate queues. - bashate bin/doc-tools-check-languages + bashate bin/doc-tools-check-languages bin/doc-tools-build-rst [testenv:releasenotes] basepython = python3 @@ -39,7 +39,8 @@ commands = {posargs} [testenv:docs] basepython = python3 -commands = python setup.py build_sphinx +commands = + sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html [testenv:bindep] # Do not install any requirements. We want this to be fast and work even if