| Message ID | 1475944231-25192-2-git-send-email-stephen@that.guru |
|---|---|
| State | Accepted |
| Delegated to: | Russell Bryant |
| Headers | show |
On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane <stephen@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@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@openvswitch.org > http://openvswitch.org/mailman/listinfo/dev >
On 15 Oct 21:20, Russell Bryant wrote: > On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane <stephen@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@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
On Mon, Oct 17, 2016 at 8:21 AM, Stephen Finucane <stephen@that.guru> wrote: > On 15 Oct 21:20, Russell Bryant wrote: > > On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane <stephen@that.guru> > 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. :-)
On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane <stephen@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@that.guru> > I've applied this whole series to master with minor tweaks mentioned in other replies. Thank you!
On Tue, 2016-10-18 at 14:44 -0400, Russell Bryant wrote: > > On Sat, Oct 8, 2016 at 12:30 PM, Stephen Finucane <stephen@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@that.guru> > > > > 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
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) + 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
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@that.guru> --- Makefile.am | 4 ++-- build-aux/dist-docs | 22 +++++++++++++++++++--- 2 files changed, 21 insertions(+), 5 deletions(-)