[ovs-dev] [PATCH 1/9] dist-docs: Add support for rST

Russell Bryant russell at ovn.org
Sun Oct 16 01:20:57 UTC 2016


On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane <stephen at that.guru> wrote:

> This will eventually go away once Sphinx starts doing all this work for
> us. For now, however, let's make sure we don't break the OVS website.
>
> This introduces a new dependency for the dist-docs script - 'rst2html'.
> This tool is packaged on Ubuntu, Fedora (via 'python-docutils'), etc.
> and can be installed from pip using the 'docsutils' package.
>
> Signed-off-by: Stephen Finucane <stephen at that.guru>
>

I'm working through this patch series now.  I had one small addition to
this one to run by you.


> ---
>  Makefile.am         |  4 ++--
>  build-aux/dist-docs | 22 +++++++++++++++++++---
>  2 files changed, 21 insertions(+), 5 deletions(-)
>
> diff --git a/Makefile.am b/Makefile.am
> index 49010b3..4b01766 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -63,8 +63,8 @@ CLEAN_LOCAL =
>  DISTCLEANFILES =
>  PYCOV_CLEAN_FILES = build-aux/check-structs,cover
>
> -# A list of Markdown-formatted documentation that will automatically be
> -# included in the "make dist-docs" output.
> +# A list of Markdown- or reStructuredText-formatted documentation that
> will
> +# automatically be included in the "make dist-docs" output.
>  docs = \
>         CONTRIBUTING.md \
>         CodingStyle.md \
> diff --git a/build-aux/dist-docs b/build-aux/dist-docs
> index a81e4b2..677ceeb 100755
> --- a/build-aux/dist-docs
> +++ b/build-aux/dist-docs
> @@ -35,6 +35,7 @@ search_path () {
>  }
>  search_path man
>  search_path markdown
> +search_path rst2html
>  search_path ps2pdf
>
>  # Create dist-docs directory.
> @@ -61,9 +62,9 @@ cat >&3 <<EOF
>  <table>
>  EOF
>
> -# Add top-level documentation to index.html, giving it .txt extensions so
> -# that the webserver doesn't serve it as Markdown and make your web
> browser
> -# try to invoke some kind of external helper you don't have installed.
> +# Add top-level documentation to index.html, giving it .txt extensions so
> that
> +# the webserver doesn't serve it as Markdown/rST and make your web
> browser try
> +# to invoke some kind of external helper you don't have installed.
>  #
>  # Also translate documentation to HTML.
>  for file
> @@ -92,6 +93,21 @@ EOF
>  EOF
>              ;;
>
> +        *.rst)
>

I added this line here:

+            title=`grep -A 1 -e "^=" $srcdir/$file | sed -n 2p`

To get a proper title for each rst doc in index.html.  Previously it was
just using the first line, which was ".." for the rst files.  Let me know
if you have an idea for something better.

+            cp "$srcdir/$file" "$distdir/$file.txt"
> +            ln -s $(basename "$file.txt") "$distdir/$file"
> +            rst2html "$distdir/$file.txt" --stylesheet-path="style.css" \
> +                --link-stylesheet --title="$file (Open vSwitch $VERSION)"
> \
> +                > "$distdir/$file.html"
> +            cat <<EOF
> +<tr>
> +  <td>$file</td>
> +  <td>$title</td>
> +  <td><a href="$file.html">HTML</a>, <a href="$file.txt">plain
> text</a></td>
> +</tr>
> +EOF
> +            ;;
> +
>          *)
>              cp "$srcdir/$file" "$distdir/$file"
>              cat <<EOF
> --
> 2.7.4
>
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> http://openvswitch.org/mailman/listinfo/dev
>



-- 
Russell Bryant



More information about the dev mailing list