diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst index fe4072d12..e58a18c0b 100644 --- a/doc/source/contributor/doc_contribute_guide.rst +++ b/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 diff --git a/new-topic.sh b/new-topic.sh index d2736cf1f..e72bd4222 100644 --- a/new-topic.sh +++ b/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 < "${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" ;; diff --git a/templates/topic-templates.txt b/templates/topic-templates.txt index e97f97f42..57f8ab949 100644 --- a/templates/topic-templates.txt +++ b/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 + 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- + +.. content here + +.. end- + +" diff --git a/tox.ini b/tox.ini index 842f3ff70..a4cb66778 100644 --- a/tox.ini +++ b/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