diff --git a/doc/doc-contrib-guide/source/doc-tools/template-generator.rst b/doc/doc-contrib-guide/source/doc-tools/template-generator.rst index 2d46591a7b..78729d3ed4 100644 --- a/doc/doc-contrib-guide/source/doc-tools/template-generator.rst +++ b/doc/doc-contrib-guide/source/doc-tools/template-generator.rst @@ -42,12 +42,12 @@ Here are a few representative files under ``www/``: * ``de`` - * ``index.html`` -- list of guides translated into $LANG* + * ``index.html`` -- list of guides translated into $LANG * ``errorpage.html`` * ``mitaka`` -- newer series have more complex page organizations; each - directory is not identical* + directory is unique * ``admin`` @@ -57,7 +57,13 @@ Here are a few representative files under ``www/``: * ``index.html`` + * ``de`` + + * ``index.html`` -- landing page for $series docs translated into $LANG + * ``index.html`` + * ``language-bindings.html`` + * ``projects.html`` * ``user`` * ``index.html`` @@ -91,7 +97,7 @@ Here are a few representative files under ``www/``: * ``index.html`` -* ``project-data`` -- YAML files with data about projects in each series +* ``project-data`` -- YAML files with data about projects in each $series * ``latest.yaml`` * ``mitaka.yaml`` @@ -102,7 +108,7 @@ Here are a few representative files under ``www/``: * ``schema.yaml`` * ``redirect-tests.txt`` -- input file for `whereto `_ - to test .htaccess; + to test ``.htaccess``; see http://files.openstack.org/docs-404s/ for a list of recent 404 errors * ``static`` -- contains files that are not templates (CSS, JS, @@ -387,8 +393,8 @@ Common tasks How would I change a page? -------------------------- -1. Look for the TEMPLATE_FILE value in the page source to find which - file produces the page +1. Look for the ``TEMPLATE_FILE`` value in the page source to find which + file produces the page. The source for https://docs.openstack.org/pike/ shows: @@ -440,7 +446,7 @@ modify it. How does the final release process work? ---------------------------------------- -See :ref:`release-task-detail`. +See :doc:`../release/taskdetail`. Testing the build ----------------- diff --git a/doc/doc-contrib-guide/source/docs-builds.rst b/doc/doc-contrib-guide/source/docs-builds.rst index f7004080dc..06d4132f7b 100644 --- a/doc/doc-contrib-guide/source/docs-builds.rst +++ b/doc/doc-contrib-guide/source/docs-builds.rst @@ -24,8 +24,9 @@ create content and contribute to the documentation. Building output locally ~~~~~~~~~~~~~~~~~~~~~~~ -You can use Linux, MacOS, or Windows to build the Sphinx documentation -everywhere in OpenStack. +Although you can use Linux, MacOS, or Windows to build locally the Sphinx +documentation for OpenStack, Linux is the preferred build environment as it +offers the most complete support for documentation building. OpenStack project and documentation repositories use a ``tox.ini`` file with specific sections that run jobs using the `Tox diff --git a/doc/doc-contrib-guide/source/docs-review-guidelines.rst b/doc/doc-contrib-guide/source/docs-review-guidelines.rst index 594aa87095..08d22b0d38 100644 --- a/doc/doc-contrib-guide/source/docs-review-guidelines.rst +++ b/doc/doc-contrib-guide/source/docs-review-guidelines.rst @@ -193,9 +193,9 @@ wait for the next proposal run. The proposal job will update the patch with the next run. If you cannot fix the problem, ask for help on the mailing lists: -* openstack-i18n: translation failures -* openstack-doc: requirements failures, glossary sync failures, - and common content sync failures. +* openstack-i18n@lists.openstack.org: translation failures +* openstack-dev@lists.openstack.org: requirements failures, glossary sync + failures, and common content sync failures. Considerations for documentation aligned with release cycles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/doc-contrib-guide/source/docs-review.rst b/doc/doc-contrib-guide/source/docs-review.rst index 7f4a54662d..e85f7db572 100644 --- a/doc/doc-contrib-guide/source/docs-review.rst +++ b/doc/doc-contrib-guide/source/docs-review.rst @@ -12,32 +12,27 @@ Reviewing documentation OpenStack documentation is treated in the same way as code, and follows the standard code review process. To see what documentation changes are ready for review, use the `Documentation Program Dashboard -`_. It is organized in groups based -on the audience for the documentation. To see current proposed changes, make -sure you register and log into https://review.openstack.org. For more details -on the review process, see `Code Review +`_ or the appropriate list of +Gerrit reviews for repositories with documentation. + +The Documentation Program Dashboard only lists changes to repositories that +are managed by the Documentation project or the project's subteams. The +Dashboard is organized in groups based on the audience for the documentation. + +To see current proposed changes, make sure you register and log into +https://review.openstack.org. For more details on the review process in +OpenStack, see `Code Review `_. Repositories and core team ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The OpenStack Documentation team is core for the openstack-manuals, -openstackdocstheme, and openstack-doc-tools projects. +The Documentation team is core for a number of repositories managed by the +Documentation project subteams. A list of those subteams is available from +:doc:`team-structure`. -For the following repositories that are part of the Documentation program, -special rules apply: - -* docs-specs: has a separate core team, - see :doc:`docs-specs ` section. -* security-doc: has a separate core team consisting of Docs team members and - Security team members. The rule here is that each patch needs an approval - by a Docs core and a Security core. -* contributor-guide, training-guides and training-labs: have separate core - teams, but also includes the openstack-manuals core team. - -The current list of docs cores for openstack-manuals can be found at -`Group openstack-doc-core -`_. +For the security-doc repository, the rule is that each patch needs an approval +by a Docs core and a Security core. Reviewing a documentation patch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -48,8 +43,13 @@ and `Code Review Guidelines `_. Once done, follow the steps below to submit a patch review. -#. Go to the `Documentation Program Dashboard +#. If you want to review patches for the repositories managed by the + Documentation project or the project's subteams, go to the + `Documentation Program Dashboard `_. + + To review patches for project teams' repositories, use the list of Gerrit + changes for the appropriate project. #. Select a patch set. #. Click a file that was uploaded to view the changes side by side. #. If you see some inconsistencies or have questions to the patch owner, @@ -78,6 +78,11 @@ Once done, follow the steps below to submit a patch review. `Peer Review `_ +.. note:: + + The following information only applies to repositories managed by the + Documentation project. + Achieving core reviewer status ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -98,23 +103,23 @@ recognizing valuable team members. The process is: -* Every month (usually on the 1st), the documentation PTL draws the top 12 - names from the `Stackalytics `_ report for - openstack-manuals: +* Every month (usually on the 1st), the documentation PTL draws the top + committers and reviewers from the `Stackalytics `_ + report for openstack-manuals: * `openstack-manuals Stackalytics `_ -* The PTL then consults the existing core team with a list of names to be - removed from and added to the core list. Once an agreement is reached, - the changes are made and advertised to the main documentation mailing list. - Cores who are being added or removed will be contacted personally before - changes are made. +* The PTL then consults the existing core team and the OpenStack community + with a list of names to be removed from and added to the core list. This is + done in public by using the openstack-dev@lists.openstack.org mailing list + as the primary communication channel. Cores who are being removed will be + contacted personally before changes are made. * Existing core team members can nominate a new core member at any time, - with a justification sent to the existing core team: - openstack-doc-core@lists.launchpad.net. Three +1 votes from other existing - core team members must be achieved for approval. + with a justification sent to the openstack-dev@lists.openstack.org mailing + list. Three +1 votes from other existing core team members must be achieved + for approval. Core reviewer responsibilities ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/doc-contrib-guide/source/release.rst b/doc/doc-contrib-guide/source/release.rst index 93f128b237..c1d6102073 100644 --- a/doc/doc-contrib-guide/source/release.rst +++ b/doc/doc-contrib-guide/source/release.rst @@ -8,7 +8,9 @@ This section describes the tasks that need to be completed to publish the documentation for an OpenStack release. It is intended to be used by the PTL and release managers. -Pike release managers are Chason Chan and Petr Kovar. +The current release manager for Documentation is listed on the +`Cross Project Liaisons wiki page +`_. .. toctree:: :maxdepth: 2 diff --git a/doc/doc-contrib-guide/source/team-structure.rst b/doc/doc-contrib-guide/source/team-structure.rst index 5177b27b97..98704032e6 100644 --- a/doc/doc-contrib-guide/source/team-structure.rst +++ b/doc/doc-contrib-guide/source/team-structure.rst @@ -27,8 +27,13 @@ with their respective leads: The current list of docs cores for openstack-manuals, openstackdocstheme, and openstack-doc-tools repositories can be found at https://review.openstack.org/#/admin/groups/30,members. + The api-site, contributor-guide, docs-specs, security-doc, training-guides, -and training-labs repositories have separate core teams. +and training-labs repositories have separate core teams but also include the +openstack-manuals core team. + +The docs-specs repository has a separate core team, see +:doc:`blueprints-and-specs` for details. The cross-project liaisons (CPLs) assist with subject matter questions, reviews, doc bug triaging, and patching docs.