From 3c9bc333ed891e4a4a9549aa5723f4c0f23168b9 Mon Sep 17 00:00:00 2001 From: Lukas Piwowarski Date: Thu, 10 Sep 2020 15:57:50 +0200 Subject: [PATCH] Fix building of the pdf documentation The .pdf documentation could not be build without errors because the source code of the documentation contained errors. In addition, there were other problems: - The readme section of the documentation was in .md format instead of .rst format. As a result, the created documentation did not look good. - The .html documentation used deprecated oslosphinx theme instead of openstackdocstheme. This patch fixes the above-mentioned problems and makes sure that the documentation is generated properly. Also, this patch updates nodejs4-docs to nodejs10-docs because the nodejs4-docs was using deprecated nodejs-npm-run-docs job [1]. [1] https://review.opendev.org/c/openstack/openstack-zuul-jobs/+/757101 Task: 35462 Depends-On: I738b833109e4caeb58bb391d79d6e63284462bd8 Change-Id: I921b15edda433c3e47456488da6d2bda07c34262 --- .zuul.yaml | 2 +- README.md | 40 ------------------------- README.rst | 60 +++++++++++++++++++++++++++++++++++++ bindep.txt | 3 +- doc/requirements.txt | 8 +++++ doc/source/conf.py | 18 ++++++++--- doc/source/contributing.rst | 3 -- doc/source/installation.rst | 7 +++-- doc/source/readme.rst | 1 + package.json | 2 +- tox.ini | 32 ++++++++++++++++++++ 11 files changed, 122 insertions(+), 54 deletions(-) delete mode 100644 README.md create mode 100644 README.rst create mode 100644 doc/requirements.txt create mode 100644 doc/source/readme.rst create mode 100644 tox.ini diff --git a/.zuul.yaml b/.zuul.yaml index 682f2c3..c9bbba6 100644 --- a/.zuul.yaml +++ b/.zuul.yaml @@ -1,4 +1,4 @@ - project: templates: - nodejs4-jobs - - nodejs4-docs + - nodejs10-docs diff --git a/README.md b/README.md deleted file mode 100644 index 5a77f65..0000000 --- a/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# eslint-config-openstack - -OpenStack has a set of style guidelines for clarity. OpenStack is a very large code base, spanning -dozens of git trees, with over a thousand developers contributing every 6 months. As such, common -style helps developers understand code in reviews, move between projects smoothly, and overall make -the code more maintainable. - -Even though eslint permits overriding rules on a per-project basis, it should be the goal of every -project to stay as close to the common guidelines as possible. - -## Installation -To add these rules to your project, follow these steps. - -1. `npm install --save-dev eslint eslint-config-openstack` -2. Add `extends: "openstack"` to your `.eslintrc` yaml file. If your project is using ES2015, add - `extends: "openstack/es2015"` instead. - -## Approval Policies - -If you would like to contribute, please follow [OpenStack's contribution guidelines](https://wiki.openstack.org/wiki/How_To_Contribute). - - -#### Rules only land with consensus -Patches that activate, deactivate, or modify rules, should only be merged if a consensus of -reviewers is reached. In this case, consensus means at least five positive votes (+1 or +2), -with no -1 votes. Cores may not override and/or ignore -1 votes. - -#### Library upgrades require two cores -Patches that upgrade eslint only require two core approvers to land. These patches must add new -upstream rules in a deactivated state, and delete any deprecated rules. - -#### Policy upgrades require all cores -Updates to policies and governance on this project require +2 votes from all direct cores on the -project. Core votes from the parent OpenStack QA project are optional. - -#### Patches should be abandoned after a month of inactivity -Cores should attempt to keep the list of extant patches small and managable. As such, they should -talk to any author whose patch has failed to garner the necessary support, and has experienced -one month of inactivity. Reasonable notice should be given to the author before a patch is -abandoned. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..47bfe66 --- /dev/null +++ b/README.rst @@ -0,0 +1,60 @@ +.. _readme: + +eslint-config-openstack +======================= + +OpenStack has a set of style guidelines for clarity. OpenStack is a very +large code base, spanning dozens of git trees, with over a thousand +developers contributing every 6 months. As such, common style helps +developers understand code in reviews, move between projects smoothly, +and overall make the code more maintainable. + +Even though eslint permits overriding rules on a per-project basis, it +should be the goal of every project to stay as close to the common +guidelines as possible. + +Installation +------------ + +To add these rules to your project, follow these steps. + +1. ``npm install --save-dev eslint eslint-config-openstack`` +2. Add ``extends: "openstack"`` to your ``.eslintrc`` yaml file. If your + project is using ES2015, add ``extends: "openstack/es2015"`` instead. + +Approval Policies +----------------- + +If you would like to contribute, please follow `OpenStack's contribution +guidelines `__. + +Rules only land with consensus +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Patches that activate, deactivate, or modify rules, should only be +merged if a consensus of reviewers is reached. In this case, consensus +means at least five positive votes (+1 or +2), with no -1 votes. Cores +may not override and/or ignore -1 votes. + +Library upgrades require two cores +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Patches that upgrade eslint only require two core approvers to land. +These patches must add new upstream rules in a deactivated state, and +delete any deprecated rules. + +Policy upgrades require all cores +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Updates to policies and governance on this project require +2 votes from +all direct cores on the project. Core votes from the parent OpenStack QA +project are optional. + +Patches should be abandoned after a month of inactivity +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Cores should attempt to keep the list of extant patches small and +managable. As such, they should talk to any author whose patch has +failed to garner the necessary support, and has experienced one month of +inactivity. Reasonable notice should be given to the author before a +patch is abandoned. diff --git a/bindep.txt b/bindep.txt index 413ec90..4507618 100644 --- a/bindep.txt +++ b/bindep.txt @@ -1,5 +1,4 @@ # This is a cross-platform list tracking distribution packages needed by tests; # see http://docs.openstack.org/infra/bindep/ for additional information. -python-sphinx [platform:dpkg] -python-oslosphinx [platform:dpkg] +tox [platform:dpkg] diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..b777f16 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,8 @@ +# 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>=2.2.0 # Apache-2.0 +sphinx>=2.0.0,!=2.1.0 # BSD +sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD + diff --git a/doc/source/conf.py b/doc/source/conf.py index f886053..e52aca4 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,10 +22,15 @@ sys.path.insert(0, os.path.abspath('../..')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinxcontrib.rsvgconverter', #'sphinx.ext.intersphinx', - 'oslosphinx' + 'openstackdocstheme' ] +# openstackdocstheme options +openstackdocs_repo_name = 'openstack/eslint-config-openstack' +openstackdocs_pdf_link = True + # autodoc generation is a bit aggressive and a nuisance when doing heavy # text edit cycles. # execute "export SPHINX_DEBUG=1" in your terminal to disable @@ -55,7 +60,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. Major themes that come with # Sphinx are currently 'default' and 'sphinxdoc'. # html_theme_path = ["."] -# html_theme = '_theme' +html_theme = 'openstackdocs' # html_static_path = ['static'] # Output file base name for HTML help builder. @@ -66,10 +71,15 @@ htmlhelp_basename = '%sdoc' % project # [howto/manual]). latex_documents = [ ('index', - '%s.tex' % project, - u'%s Documentation' % project, + 'doc-%s.tex' % project, + u'Eslint-config-openstack Documentation', u'OpenStack Foundation', 'manual'), ] # Example configuration for intersphinx: refer to the Python standard library. #intersphinx_mapping = {'http://docs.python.org/': None} + +latex_use_xindy = False +latex_elements = { + 'extraclassoptions': 'openany,oneside', +} diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 589744c..2915337 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -10,9 +10,6 @@ project, the following will help get you started. Contributor License Agreement ----------------------------- -.. index:: - single: license; agreement - In order to contribute to the project, you need to have signed OpenStack's contributor's agreement. diff --git a/doc/source/installation.rst b/doc/source/installation.rst index fc06f9d..3ce5cf4 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -8,7 +8,8 @@ To add these rules to your project, follow these steps. 1. Install the npm package to your project: - `npm install --save-dev eslint eslint-config-openstack` + ``npm install --save-dev eslint eslint-config-openstack`` + +2. Add ``extends: "openstack"`` to your ``.eslintrc`` yaml file. + If your project is using ES2015, add ``extends: "openstack/es2015"`` instead. -2. Add `extends: "openstack"` to your `.eslintrc` yaml file. - If your project is using ES2015, add `extends: "openstack/es2015"` instead. diff --git a/doc/source/readme.rst b/doc/source/readme.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/doc/source/readme.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/package.json b/package.json index 3993d8a..7fc112a 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,7 @@ "scripts": { "test": "jasmine", "lint": "eslint ./", - "docs": "cd ./doc && make html" + "docs": "tox -e docs" }, "repository": { "type": "git", diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..2764a2c --- /dev/null +++ b/tox.ini @@ -0,0 +1,32 @@ +[tox] +minversion = 2.4.0 +skipsdist = True +ignore_basepython_conflict = True + +[testenv] +basepython = python3 +setenv = + VIRTUAL_ENV={envdir} + OS_LOG_CAPTURE=1 + OS_STDOUT_CAPTURE=1 + OS_STDERR_CAPTURE=1 + OS_TEST_TIMEOUT=160 + PYTHONWARNINGS=default::DeprecationWarning,ignore::DeprecationWarning:distutils,ignore::DeprecationWarning:site + +[testenv:docs] +deps = + -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/doc/requirements.txt +commands = + rm -rf doc/build + sphinx-build -W -b html doc/source doc/build/html +whitelist_externals = rm + +[testenv:pdf-docs] +deps = {[testenv:docs]deps} +whitelist_externals = + make +commands = + sphinx-build -W -b latex doc/source doc/build/pdf + make -C doc/build/pdf +