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

[Stephen Fincane]

On Tue, 2016-10-18 at 14:44 -0400, Russell Bryant wrote:
> 
> On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane 
> 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 
> > 
> 
> I've applied this whole series to master with minor tweaks mentioned
> in other replies.  Thank you!

Lovely job. Thanks, Russell. Onto series two, now :)

Stephen
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev

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

[Russell Bryant]

On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane  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 
>

I've applied this whole series to master with minor tweaks mentioned in
other replies.  Thank you!

-- 
Russell Bryant


-- 
Russell Bryant
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev

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

[Russell Bryant]

On Mon, Oct 17, 2016 at 8:21 AM, Stephen Finucane  wrote:

> On 15 Oct 21:20, Russell Bryant wrote:
> > On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane 
> wrote:
> > 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.
>

Ha, consider this line on me while it lasts.  :-)

-- 
Russell Bryant
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev

Re: [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  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 
> >
> 
> 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
> >
> > -# 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
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev

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

[Russell Bryant]

On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane  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 
>

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
>
> -# 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 < +
> +  $file
> +  $title
> +  HTML, plain
> text
> +
> +EOF
> +;;
> +
>  *)
>  cp "$srcdir/$file" "$distdir/$file"
>  cat < --
> 2.7.4
>
> ___
> dev mailing list
> dev@openvswitch.org
> http://openvswitch.org/mailman/listinfo/dev
>



-- 
Russell Bryant
___
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev