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

[Stephen Finucane]

On 15 Oct 21:20, Russell Bryant wrote:
> 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.

Sure thing. This is an intermediate step on the way to Sphinx, so
whatever works is fine by. Just don't expect me to debug anything
involving sed or awk, heh.

Stephen