From d95543fe94c74a8ffe495ce9867582dd6beef772 Mon Sep 17 00:00:00 2001 From: Ron Stone Date: Mon, 27 Sep 2021 11:13:17 -0400 Subject: [PATCH] Document unique file name generator Instructions for using unique import generator submitted under https://review.opendev.org/c/starlingx/docs/+/810950 Incorporated review comments. Signed-off-by: Ron Stone Change-Id: I72de341a99b8fc1308fb769119896247caf073ce Signed-off-by: Ron Stone --- .../contributor/doc_contribute_guide.rst | 134 ++++++++++++++++++ doc/source/shared/abbrevs.txt | 1 + 2 files changed, 135 insertions(+) diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst index 8abb3d675..ac9a6eef0 100644 --- a/doc/source/contributor/doc_contribute_guide.rst +++ b/doc/source/contributor/doc_contribute_guide.rst @@ -168,6 +168,140 @@ between the StarlingX and OpenStack practices are highlighted below. Configure endpoint ------------------ +.. _create-rst-files: + +---------------- +Create rST Files +---------------- + +Use the :command:`tox -e newfile` command to create new |RST| files. + +.. rubric:: |context| + +All |RST| files created in StarlingX documentation repositories must have the +following characteristics: + +* They must have unique file names. +* They must have |RST| labels at the beginning of the files that match the file + names. + +.. important:: + These rules apply to *index* files as well as those containing user + documentation. + +A utility is available for use from within each documentation repository you +have installed to generate uniquely named files for you. + +.. rubric:: |prereq| + +You must have :program:`uuidgen` installed on your system. This program is +included by default on most modern Linux distributions. If it is not installed, +consult your distribution's documentation for instructions. + +.. rubric:: |proc| + +#. Change to the directory where you wish to create a new topic. + + Typically, this will be below the :file:`doc/source` directory of the + repository. + +#. Run the following :command:`tox` command. + + .. code-block:: bash + + tox -e newfile + +#. When prompted, enter a title for the new topic. + + .. code-block:: none + :emphasize-lines: 3 + + You are about to create a new reStructuredText file in + + /home/jdoe/starlingx/docs/doc/source/intro + + If this is not what you want, press CTL-C to quit and change to the directory + you want to create the file in. + + Enter a title for the new topic. The file name and topic label used for + linking will be based on this value. + + + Topic title: + + #. Review the directory (an example is highlighted above) that the utility + will create the new file in. + + #. If this is not correct, press :kbd:`CTL-C` to quit, change to the correct + directory, and run the command again; otherwise, type the topic title and + press :kbd:`ENTER`. + +#. When prompted, select the type of |RST| stub file you want to create. + + .. code-block:: none + + Thanks. Now choose a topic type. Enter one of the following characters: + + t) A task topic. Will contain the outline of a procedure. + i) An index. + r) A reference topic. Will contain a minimal list-table definition. + g) A minimal generic topic. + Topic type: + + Each option creates a stub file with different templated content useful for + getting started. Press the corresponding key. + +.. rubric:: |result| + +The new |RST| file is created. + + +The title used in the new |RST| file matches what you typed exactly. However, +some changes have been made to the file name and topic label. + +For example, if you entered ``Architectural Considerations!`` as a title, +listing the directory will show a file similar to the following: + +.. code-block:: bash + + ls + +.. code-block:: none + + architectural-considerations--d9dd4c105700.rst + +The following changes were made: + +* All alphabetical characters were converted to lower case. +* All spaces and special characters, such as the ``!`` were replaced by + dashes. +* A final dash and 12 digit random string were appended to the file name. +* The extension :file:`.rst` was added. +* If you chose to create an ``index`` file by selecting :kbd:`i` when prompted, + :file:`index-` was prepended to the file name. + +Examining the file reveals that the label matches the file name, while the +title is preserved as typed. + +.. code-block:: bash + + cat architectural-considerations--d9dd4c105700.rst + +.. code-block:: none + :emphasize-lines: 1,4 + + .. _architectural-considerations--d9dd4c105700: + + ============================= + Architectural Considerations! + ============================= + + .. content here + +When you reference this file in ``toctree`` and ``ref`` directives, use +the file name/label string like this: ``architectural-considerations--d9dd4c105700`` + + --------------- RST conventions --------------- diff --git a/doc/source/shared/abbrevs.txt b/doc/source/shared/abbrevs.txt index 408d8fe15..7d5f28084 100755 --- a/doc/source/shared/abbrevs.txt +++ b/doc/source/shared/abbrevs.txt @@ -97,6 +97,7 @@ .. |RBAC| replace:: :abbr:`RBAC (Role-Based Access Control)` .. |RBD| replace:: :abbr:`RBD (RADOS Block Device)` .. |RPC| replace:: :abbr:`RPC (Remote Procedure Call)` +.. |RST| replace:: :abbr:`rST (reStructuredText)` .. |SAN| replace:: :abbr:`SAN (Subject Alternative Name)` .. |SANs| replace:: :abbr:`SANs (Subject Alternative Names)` .. |SAS| replace:: :abbr:`SAS (Serial Attached SCSI)`