Extent usage of UUID filenames

Extend newfile script to generate unique filenames for
include files.
Update instructions in Contributor guide
Include correct version of new-topic.sh
Fix script output in Contributor guide

Signed-off-by: Ron Stone <ronald.stone@windriver.com>
Change-Id: I049adb2a8b8b028c45e2fc4f951db664e4777550
This commit is contained in:
Ron Stone 2021-12-21 07:08:16 -05:00
parent 77dace0f1c
commit 4cdf447ece
4 changed files with 61 additions and 8 deletions

View File

@ -220,6 +220,8 @@ consult your distribution's documentation for instructions.
/home/jdoe/starlingx/docs/doc/source/intro /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 If this is not what you want, press CTL-C to quit and change to the directory
you want to create the file in. 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 #. Review the directory (an example is highlighted above) that the utility
will create the new file in. 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 #. 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 directory, and run the command again; otherwise, type the topic title and
press :kbd:`ENTER`. press :kbd:`ENTER`.
@ -246,6 +254,7 @@ consult your distribution's documentation for instructions.
i) An index. i) An index.
r) A reference topic. Will contain a minimal list-table definition. r) A reference topic. Will contain a minimal list-table definition.
g) A minimal generic topic. g) A minimal generic topic.
f) A content fragment included in an rST file. Will be saved to doc/source/_includes.
Topic type: Topic type:
Each option creates a stub file with different templated content useful for 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 architectural-considerations--d9dd4c105700.rst
The following changes were made: The following changes were made.
* All alphabetical characters were converted to lower case. * All alphabetical characters were converted to lower case.
* All spaces and special characters, such as the ``!`` were replaced by * All spaces and special characters, such as the ``!`` were replaced by
dashes. dashes.
* A final dash and 12 digit random string were appended to the file name. * 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, * If you chose to create an ``index`` file by selecting :kbd:`i` when prompted,
:file:`index-` was prepended to the file name. :file:`index-` was prepended to the file name.
Examining the file reveals that the label matches the file name, while the 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 .. code-block:: bash

View File

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

View File

@ -76,3 +76,28 @@ $strike
.. content here .. 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>
"

View File

@ -44,6 +44,6 @@ commands = {posargs}
passenv=PWD passenv=PWD
commands = commands =
bash -c "echo Running in {env:PWD}" 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 whitelist_externals = new-topic.sh
bash bash