Merge "Extent usage of UUID filenames"

doc/source/contributor/doc_contribute_guide.rst

@@ -220,6 +220,8 @@ consult your distribution's documentation for instructions.
 
        /home/jdoe/starlingx/docs/doc/source/intro
 
+       or a content fragment file in doc/source/_includes
+
        If this is not what you want, press CTL-C to quit and change to the directory
        you want to create the file in.
 
@@ -232,6 +234,12 @@ consult your distribution's documentation for instructions.
    #. Review the directory (an example is highlighted above) that the utility
       will create the new file in.
 
+      .. note::
+         This does not apply if you choose to create a content fragment using
+         the :kbd:`f` option when prompted. In that case, the file will be
+         saved to :file:`doc/source/_includes` regardless of your current
+         working directory.
+
    #. 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`.
@@ -246,6 +254,7 @@ consult your distribution's documentation for instructions.
       i) An index.
       r) A reference topic. Will contain a minimal list-table definition.
       g) A minimal generic topic.
+      f) A content fragment included in an rST file. Will be saved to doc/source/_includes.
       Topic type:
 
    Each option creates a stub file with different templated content useful for
@@ -270,18 +279,20 @@ listing the directory will show a file similar to the following:
 
     architectural-considerations--d9dd4c105700.rst
 
-The following changes were made:
+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.
+* The extension :file:`.rst` was added for all options except :kbd:`f`, in
+  which case the extension :file:`.rest` 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.
+title is preserved as typed. No label was added if you selected :kbd:`f`.
 
 .. code-block:: bash
 

new-topic.sh

@@ -5,6 +5,8 @@ if ! hash uuidgen 2>/dev/null; then
   exit 1
 fi
 
+INCLUDEDIR="$2/doc/source/_includes"
+
 ask_name () {
 
    echo -e "`cat <<EOF
@@ -13,6 +15,8 @@ ask_name () {
 
    ${WD}
 
+   or a content fragment file in doc/source/_includes
+
    If this is not what you want, press CTL-C to quit and change to the directory
    you want to create the file in.
 
@@ -45,6 +49,7 @@ ask_type () {
     i) An index.
     r) A reference topic. Will contain a minimal list-table definition.
     g) A minimal generic topic.
+    f) A content fragment included in an rST file. Will be saved to doc/source/_includes.
 
 EOF`"
 
@@ -52,7 +57,7 @@ EOF`"
 
        case $input in
 
-           t|i|r|g)
+           t|i|r|g|f)
               break
              ;;
 
@@ -69,9 +74,17 @@ EOF`"
 
 write_stub () {
 
-   echo "$1" > "${WD}/${filename}.rst"
-   if [[ -f ${WD}/${filename}.rst ]]; then
-     echo -e "\nCreated ${WD}/${filename}.rst"
+   if [[ $input == "f" ]]; then
+     outdir=$INCLUDEDIR
+     ext="rest"
+   else
+     outdir=$WD
+     ext="rst"
+   fi
+
+   echo "$1" > "${outdir}/${filename}.${ext}"
+   if [[ -f ${outdir}/${filename}.${ext} ]]; then
+     echo -e "\nCreated ${outdir}/${filename}.${ext}"
      exit 0
    else
      exit 1
@@ -127,6 +140,10 @@ case $input in
       write_stub "${topic}"
       ;;
 
+   f)
+      write_stub "${include}"
+      ;;
+
    *)
       echo -e "$input not valid"
       ;;

templates/topic-templates.txt

@@ -76,3 +76,28 @@ $strike
 .. content here
 
 "
+
+# include file
+include="
+.. If this file will contain only one text fragment, delete the \".. begin-\" and 
+   \".. end-\" comments below and simply include your rST content.
+   
+.. If this file will include more than one text fragment, replace <comment-name>
+   with a string describing the fragment. This string must be unique and contain
+   no spaces. Comments must match for each fragment, for example:
+   .. begin-source-env-note
+   .. end-source-env-note
+   Repeat this pattern for each fragment in the file.
+   
+.. This file should be saved to the doc/source/_include directory of your project.
+
+.. For more information on including content fragments, see:
+   https://docutils.sourceforge.io/docs/ref/rst/directives.html#include
+
+.. begin-<comment-name>
+
+.. content here
+
+.. end-<comment-name>
+
+"

tox.ini

@@ -44,6 +44,6 @@ commands = {posargs}
 passenv=PWD
 commands =
        bash -c "echo Running in {env:PWD}"
-       bash new-topic.sh {env:PWD}
+       bash new-topic.sh {env:PWD} {toxinidir}
 whitelist_externals = new-topic.sh
                       bash