From 8ca967a7fdf2c1879af7d3c6ae49ac880a21136d Mon Sep 17 00:00:00 2001 From: Sean McGinnis Date: Tue, 16 Oct 2018 11:58:30 -0500 Subject: [PATCH] Fix format errors in PTI docs Extra spaces and unnecessary tags are causing sections to be block quoted and other incorrect formatting in the rendered output. Change-Id: Ibe3d35e6983febe4171a0f282e2016d342f2a817 Signed-off-by: Sean McGinnis --- reference/pti/golang.rst | 119 ++++++++++++++++++----------------- reference/pti/javascript.rst | 79 +++++++++++------------ reference/pti/python.rst | 34 +++++----- 3 files changed, 117 insertions(+), 115 deletions(-) diff --git a/reference/pti/golang.rst b/reference/pti/golang.rst index de341ef16..7a040c8d6 100644 --- a/reference/pti/golang.rst +++ b/reference/pti/golang.rst @@ -14,13 +14,13 @@ and they follow OpenStack processes where feasible. Each golang project must be able to do: - - Dependency installation - - Code style checks - - Unit tests - - Functional tests - - Test Coverage Report - - Documentation generation - - Translations import/export and merge for translated projects +- Dependency installation +- Code style checks +- Unit tests +- Functional tests +- Test Coverage Report +- Documentation generation +- Translations import/export and merge for translated projects There is not yet a consensus among the to golang community for build and package management tools as the ``go`` tool itself was intended to @@ -41,40 +41,40 @@ Specific commands To drive the above tasks, the following commands should be supported in a clean tree: - :code:`make depend` - Install dependencies required to build the project +``make depend`` + Install dependencies required to build the project - :code:`make build` - Execute build process +``make build`` + Execute build process - :code:`make install` - Execute binary install +``make install`` + Execute binary install - :code:`make test` - Execute tests +``make test`` + Execute tests - :code:`make fmt` - Execute code style checks +``make fmt`` + Execute code style checks - :code:`make docs` - Generate HTML documentation from the in-tree developer docs +``make docs`` + Generate HTML documentation from the in-tree developer docs - :code:`make godoc` - Generate the golang docs from the source +``make godoc`` + Generate the golang docs from the source - :code:`make releasenotes` - Generate HTML release notes +``make releasenotes`` + Generate HTML release notes Additional commands may be supported, but are not required: - :code:`make cover` - Generate coverage reports +``make cover`` + Generate coverage reports - :code:`make lint` - Execute more code style checks +``make lint`` + Execute more code style checks - :code:`make translation` - Perform translation-related tasks (TBD) +``make translation`` + Perform translation-related tasks (TBD) Project Setup ------------- @@ -82,24 +82,25 @@ Project Setup Project repos shall use a structure that is a hybrid of the typical OpenStack structure and those commonly found in the golang community. Because these are OpenStack projects, the top-level structure shall contain -the existing process-related components. All golang source code and modules shall -be in one or more subdirectories named in a manner to identify its contents -distinctly from the Python namespace directories currently used. +the existing process-related components. All golang source code and modules +shall be in one or more subdirectories named in a manner to identify its +contents distinctly from the Python namespace directories currently used. This allows the golang code to maintain its native style and not be mixed in with the OpenStack tool-related pieces such as Sphinx documentation and Reno release notes. The source subdirectory naming is intentionally flexible in order to accommodate unforeseen situations, however the following guidelines should -be strongly considered:: +be strongly considered: - - Simple projects or projects that only need one golang workspace can use - a single top-level directory named ``go``. - - Projects that may have multiple distinct golang workspaces should use - names that include a ``-go`` suffix. This allows similarly named modules - in multiple languages to co-exist. For example: the CloudTool project - should continue to put Python sources in its Python namespace ``cloudtool`` - and the golang source in ``cloudtool-go`` (do not use a period!). +- Simple projects or projects that only need one golang workspace can use + a single top-level directory named ``go``. + +- Projects that may have multiple distinct golang workspaces should use + names that include a ``-go`` suffix. This allows similarly named modules + in multiple languages to co-exist. For example: the CloudTool project + should continue to put Python sources in its Python namespace ``cloudtool`` + and the golang source in ``cloudtool-go`` (do not use a period!). Dependency Management --------------------- @@ -108,8 +109,8 @@ OpenStack has chosen to use Glide_ as the common dependency management tool for golang. The ``depend`` target provides a common interface to Glide's ``install`` command. - :code:`make depend` - Install dependencies required to build the project +``make depend`` + Install dependencies required to build the project Golang dependencies shall not be vendored in golang repos. Each project shall include a list of its dependencies and acceptable/tested versions in the repo. @@ -144,11 +145,11 @@ other operations such as ``go test``. Build and install are split out here as they are common operations and useful in their own right. These targets are not strictly necessary for CI testing. - :code:`make build` - Execute build process +``make build`` + Execute build process - :code:`make install` - Execute binary install +``make install`` + Execute binary install Codestyle Checks ---------------- @@ -159,12 +160,12 @@ target shall not use ``go fmt`` which rewrites source files by default. As a developer convenience a second target called ``fmtfix`` shall be defined that does the source fixups (equivalent to ``gofmt -l -w``). - :code:`make fmt` - Run the gofmt tool non-destructively to validate code formatting +``make fmt`` + Run the gofmt tool non-destructively to validate code formatting - :code:`make fmtfix` - Run the gofmt tool and overwrite source files with gofmt's version - if changes are required. This is primarily a developer convenience. +``make fmtfix`` + Run the gofmt tool and overwrite source files with gofmt's version + if changes are required. This is primarily a developer convenience. Tests ----- @@ -172,8 +173,8 @@ Tests OpenStack uses ``go test`` to run all test types at once invoked via the ``Makefile``. - :code:`make test` - Run tests +``make test`` + Run tests This is the general test target and may simply call some subset of additional ``test-*`` targets. Specific test targets should be named with a ``test-*`` @@ -203,8 +204,8 @@ Sphinx to generate our Narrative Project documentation. In addition to the normal PTI :ref:`pti-documentation` requirements, for developer convenience, Go projects are recommended to provide: - :code:`make docs` - Generate HTML documentation from the in-tree developer docs +``make docs`` + Generate HTML documentation from the in-tree developer docs that should: @@ -220,8 +221,8 @@ Go has a well-defined documentation tool `godoc`_ that produces developer documentation extracted from source code comments, similar to Python's Docstring. - :code:`make godoc` - Generate the golang docs from the source +``make godoc`` + Generate the golang docs from the source .. TBD(dtroyer): define how the godoc output is integrated with the current .. sphinx process @@ -237,8 +238,8 @@ the final HTML documentation. In addition to the normal PTI :ref:`pti-documentation` requirements, for developer convenience, Go projects are recommended to provide: - :code:`make releasenotes` - Generate HTML release notes +``make releasenotes`` + Generate HTML release notes Translations ------------ diff --git a/reference/pti/javascript.rst b/reference/pti/javascript.rst index faf30b136..cf8ddbf98 100644 --- a/reference/pti/javascript.rst +++ b/reference/pti/javascript.rst @@ -5,23 +5,23 @@ Project Testing Interface: JavaScript This document outlines common ways to meet the Project Testing Interface requirements for JavaScript. Each JavaScript project must be able to do: - - Codestyle checks. - - Execute Tests and Code Coverage - - Package Tarball Generation - - Documentation Generation - - Validate dependency licenses +- Codestyle checks. +- Execute Tests and Code Coverage +- Package Tarball Generation +- Documentation Generation +- Validate dependency licenses Projects which are browser based must also be able to do: - - Unit tests in Firefox and Chromium. +- Unit tests in Firefox and Chromium. Projects which are server based must also be able to do: - - Unit tests in Node.js. +- Unit tests in Node.js. Projects which require translation must also be able to do: - - Translation import/export and merge for translated objects. +- Translation import/export and merge for translated objects. Specific commands ----------------- @@ -29,31 +29,31 @@ Specific commands The following commands must be supported at the root of a clean tree, in order to initialize your project. - :code:`npm install` +``npm install`` This command installs all of the project's dependencies. To drive the above required steps, the following commands should be supported at the root of an initialized tree. - :code:`npm test` +``npm test`` This command executes all available test suites, and generate appropriate code coverage reports. - :code:`npm run lint` +``npm run lint`` This command performs codestyle checks against the project. - :code:`npm pack` +``npm pack`` This command generates a release tarball. - :code:`npm publish --no-scripts` +``npm publish --no-scripts`` This command will publish a release tarball to npm. It may not be necessary for all projects. - :code:`npm run document` +``npm run document`` This command builds documentation for the project. The following commands are still under discussion: - :code:`npm run license` +``npm run license`` This command ensures that no incompatible licenses have accidentally been included. - :code:`npm run translate` +``npm run translate`` This command imports translations into this project, if necessary. @@ -80,13 +80,13 @@ Requirements Listing Each project should list its runtime, peer, and development dependencies in package.json and (if applicable) bower.json. - :code:`dependencies` +``dependencies`` Packages required by your project to run in production. These should never use fuzzy version matching. - :code:`devDependencies` +``devDependencies`` Packages that are required by your project during the test and build phase. These should never use fuzzy version matching. - :code:`peerDependencies` +``peerDependencies`` Packages that are used to run your project, but whose version does not strictly matter. For example, eslint-config-openstack has eslint as a peer dependency. @@ -104,7 +104,7 @@ expected output. Codestyle Checks ================ -:Command: :code:`npm run lint` +:Command: ``npm run lint`` OpenStack requires the custom npm script 'lint' to execute our codestyle checks. The tool we use is called `ESLint`_, and our rules are published to npm @@ -112,69 +112,70 @@ as eslint-config-openstack_. Executing Tests and Code Coverage ================================= -:Command: :code:`npm test` +:Command: ``npm test`` OpenStack requires a sane testing and code coverage strategy for each project, though we do not prescribe the tools and coverage threshold, as these may differ based on circumstance and project type. Generated test -reports should be placed in :code:`./reports` in your projects' root directory. -Generated coverage output should similarly be placed in :code:`./cover`. +reports should be placed in `./reports` in your projects' root directory. +Generated coverage output should similarly be placed in `./cover`. Package Tarball Generation ========================== -:Command: :code:`npm pack` +:Command: ``npm pack`` -OpenStack uses :code:`npm pack` to generate a release tarball, which will -compile all files listed in :code:`package.json`. If your project requires +OpenStack uses ``npm pack`` to generate a release tarball, which will +compile all files listed in `package.json`. If your project requires concatenation, minification, or any other preprocessing to create a valid -tarball, you may use the npm :code:`prepublish` hook to trigger these steps. +tarball, you may use the npm `prepublish` hook to trigger these steps. All packages should include: - - A README - - A LICENSE file - - All source code +- A README +- A LICENSE file +- All source code Generate Documentation ====================== -:Command: :code:`npm run document` +:Command: ``npm run document`` In order to reuse existing templates, styles, and tooling, OpenStack uses Sphinx to generate our JavaScript Project documentation. In addition to the normal PTI :ref:`pti-documentation` requirements, Javascript -projects are recommended to provide an :code:`npm run document` command for +projects are recommended to provide an `npm run document` command for developer convenience that should: * Either install any needed distro dependencies from the ``doc`` tag in ``bindep.txt`` or emit an error if they are not installed. * Install Python dependencies for Sphinx from ``doc/requirements.txt``. -* Execute ``sphinx-build -b html doc/source doc/build`` +* Execute ``sphinx-build-b html doc/source doc/build`` The project infrastructure will not use ``npm`` to build the documentation. Therefore it is **STRONGLY** discouraged for people to put additional logic -into the :code:`npm run document` command. Additional logic needed around +into the `npm run document` command. Additional logic needed around Sphinx generation should go into Sphinx plugins which should be listed in ``doc/requirements.txt``. Generate Release Notes ====================== -:Command: :code:`npm run releasenotes` +:Command: ``npm run releasenotes`` OpenStack uses `reno `_ for generating release notes. In addition to the normal PTI :ref:`pti-documentation` requirements, Javascript -projects are recommended to provide an :code:`npm run releasenotes` command for +projects are recommended to provide an `npm run releasenotes` command for developer convenience that should: * Either install any needed distro dependencies from the ``releasenotes`` tag in ``bindep.txt`` or emit an error if they are not installed. -* Execute: ``sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html`` +* Execute: ``sphinx-build -a -E -W -d releasenotes/build/doctrees-b html + releasenotes/source releasenotes/build/html`` -The project infrastructure will not use :code:`npm run releasenotes` to build +The project infrastructure will not use `npm run releasenotes` to build the release notes. Therefore it is **STRONGLY** discouraged for people to put -additional logic into the :code:`npm run releasenotes` command. Additional +additional logic into the `npm run releasenotes` command. Additional logic needed should go into reno. .. _NPM package scripts: https://docs.npmjs.com/misc/scripts diff --git a/reference/pti/python.rst b/reference/pti/python.rst index 0ea75f29f..585b646c7 100644 --- a/reference/pti/python.rst +++ b/reference/pti/python.rst @@ -6,16 +6,16 @@ Project Testing Interface: Python Each python project must be able to do: - - Unit tests for python2.7 - - Codestyle checks - - Testing Coverage Report - - Source Tarball Generation - - Translations import/export and merge for translated projects - - Documentation generation +- Unit tests for python2.7 +- Codestyle checks +- Testing Coverage Report +- Source Tarball Generation +- Translations import/export and merge for translated projects +- Documentation generation Projects which are compatible with Python 3 must also be able to do: - - Unit tests for python3.5 +- Unit tests for python3.5 Specific commands ----------------- @@ -23,21 +23,21 @@ Specific commands To drive the above tasks, the following commands should be supported in a clean tree: - - tox -epy27 - - tox -epep8 - - tox -ecover - - python setup.py sdist - - python setup.py bdist_wheel - - sphinx-build -W -b html doc/source doc/build +- ``tox -e py27`` +- ``tox -e pep8`` +- ``tox -e cover`` +- ``python setup.py sdist`` +- ``python setup.py bdist_wheel`` +- ``sphinx-build -W -b html doc/source doc/build`` Projects that are translated should also support: - - tox -evenv python setup.py extract_messages - - tox -evenv python setup.py update_catalog +- ``tox -e venv python setup.py extract_messages`` +- ``tox -e venv python setup.py update_catalog`` Projects which are compatible with Python 3 must also be able to do: - - tox -epy35 +- ``tox -e py35`` Some basic prerequisites for test running (system packages, database configuration, custom filesystem types) are acceptable as long as they are @@ -159,7 +159,7 @@ a ``releasenotes`` environment for tox that will run sphinx-build -a -E -W -d releasenotes/build/doctrees -b html \ releasenotes/source releasenotes/build/html -The project infrastructure will not use ``tox -ereleasenotes`` to build the +The project infrastructure will not use ``tox -e releasenotes`` to build the documentation. Therefore it is **STRONGLY** discouraged for people to put additional logic into the command section of that tox environment. Additional logic needed around releasenotes generation should go into reno.