| Message ID | 20170103213305.23838-1-stephen@that.guru |
|---|---|
| State | Accepted |
| Headers | show |
On Tue, 2017-01-03 at 21:33 +0000, Stephen Finucane wrote: > The recently published 'ovs' theme [1] copies the styling of the Open > vSwitch website. Start using this, with fallbacks for users who do > not > have the package installed. > > This extends support for building docs to users of Sphinx 1.2 as the > previous theme - bizstyle - was only available in 1.3+. Oops - forgot [1]. [1] https://pypi.python.org/pypi/ovs-sphinx-theme Stephen > Signed-off-by: Stephen Finucane <stephen@that.guru> > --- > Documentation/conf.py | 20 ++++++++++++++++---- > Documentation/requirements.txt | 3 ++- > 2 files changed, 18 insertions(+), 5 deletions(-)
On Wed, Jan 04, 2017 at 09:03:04AM +0000, Stephen Finucane wrote: > On Tue, 2017-01-03 at 21:33 +0000, Stephen Finucane wrote: > > The recently published 'ovs' theme [1] copies the styling of the Open > > vSwitch website. Start using this, with fallbacks for users who do > > not > > have the package installed. > > > > This extends support for building docs to users of Sphinx 1.2 as the > > previous theme - bizstyle - was only available in 1.3+. > > Oops - forgot [1]. > > [1] https://pypi.python.org/pypi/ovs-sphinx-theme > > Stephen > > > Signed-off-by: Stephen Finucane <stephen@that.guru> Thanks, I added the footnote and pushed this to master.
On Wed, 2017-01-04 at 08:00 -0800, Ben Pfaff wrote: > On Wed, Jan 04, 2017 at 09:03:04AM +0000, Stephen Finucane wrote: > > On Tue, 2017-01-03 at 21:33 +0000, Stephen Finucane wrote: > > > The recently published 'ovs' theme [1] copies the styling of the > > > Open > > > vSwitch website. Start using this, with fallbacks for users who > > > do > > > not > > > have the package installed. > > > > > > This extends support for building docs to users of Sphinx 1.2 as > > > the > > > previous theme - bizstyle - was only available in 1.3+. > > > > Oops - forgot [1]. > > > > [1] https://pypi.python.org/pypi/ovs-sphinx-theme > > > > Stephen > > > > > Signed-off-by: Stephen Finucane <stephen@that.guru> > > Thanks, I added the footnote and pushed this to master. ...and I've updated the readthedocs.org config to use Documentation/requirements.txt. Looks good to me. Stephen
On Wed, Jan 04, 2017 at 04:06:26PM +0000, Stephen Finucane wrote: > On Wed, 2017-01-04 at 08:00 -0800, Ben Pfaff wrote: > > On Wed, Jan 04, 2017 at 09:03:04AM +0000, Stephen Finucane wrote: > > > On Tue, 2017-01-03 at 21:33 +0000, Stephen Finucane wrote: > > > > The recently published 'ovs' theme [1] copies the styling of the > > > > Open > > > > vSwitch website. Start using this, with fallbacks for users who > > > > do > > > > not > > > > have the package installed. > > > > > > > > This extends support for building docs to users of Sphinx 1.2 as > > > > the > > > > previous theme - bizstyle - was only available in 1.3+. > > > > > > Oops - forgot [1]. > > > > > > [1] https://pypi.python.org/pypi/ovs-sphinx-theme > > > > > > Stephen > > > > > > > Signed-off-by: Stephen Finucane <stephen@that.guru> > > > > Thanks, I added the footnote and pushed this to master. > > ...and I've updated the readthedocs.org config to use > Documentation/requirements.txt. Looks good to me. I've noticed that when I run "make htmldocs", I always get this warning: Cannot find 'ovs_sphinx' package. Falling back to default theme. Is that expected?
On Wed, 2017-01-04 at 08:32 -0800, Ben Pfaff wrote: > On Wed, Jan 04, 2017 at 04:06:26PM +0000, Stephen Finucane wrote: > > On Wed, 2017-01-04 at 08:00 -0800, Ben Pfaff wrote: > > > On Wed, Jan 04, 2017 at 09:03:04AM +0000, Stephen Finucane wrote: > > > > On Tue, 2017-01-03 at 21:33 +0000, Stephen Finucane wrote: > > > > > The recently published 'ovs' theme [1] copies the styling of > > > > > the > > > > > Open > > > > > vSwitch website. Start using this, with fallbacks for users > > > > > who > > > > > do > > > > > not > > > > > have the package installed. > > > > > > > > > > This extends support for building docs to users of Sphinx 1.2 > > > > > as > > > > > the > > > > > previous theme - bizstyle - was only available in 1.3+. > > > > > > > > Oops - forgot [1]. > > > > > > > > [1] https://pypi.python.org/pypi/ovs-sphinx-theme > > > > > > > > Stephen > > > > > > > > > Signed-off-by: Stephen Finucane <stephen@that.guru> > > > > > > Thanks, I added the footnote and pushed this to master. > > > > ...and I've updated the readthedocs.org config to use > > Documentation/requirements.txt. Looks good to me. > > I've noticed that when I run "make htmldocs", I always get this > warning: > Cannot find 'ovs_sphinx' package. Falling back to default > theme. > Is that expected? Yes, I have a fallback inserted [1] so that people who don't want to install anything non-apt/dnf packages can still build the docs locally. You can get rid of this package by installing the requirements locally. $ sudo pip install -r Documentation/requirements.txt $ make htmldocs ...which is what docs.openvswitch.org does now. The building docs page [2] should probably be updated to reflect this. [1] https://github.com/openvswitch/ovs/blob/e25d4af1e690d1091089aefb5b9 fde31825252d4/Documentation/conf.py#L25-L27 [2] http://docs.openvswitch.org/en/latest/intro/install/documentation/
On Wed, Jan 04, 2017 at 04:38:55PM +0000, Stephen Finucane wrote: > On Wed, 2017-01-04 at 08:32 -0800, Ben Pfaff wrote: > > On Wed, Jan 04, 2017 at 04:06:26PM +0000, Stephen Finucane wrote: > > > On Wed, 2017-01-04 at 08:00 -0800, Ben Pfaff wrote: > > > > On Wed, Jan 04, 2017 at 09:03:04AM +0000, Stephen Finucane wrote: > > > > > On Tue, 2017-01-03 at 21:33 +0000, Stephen Finucane wrote: > > > > > > The recently published 'ovs' theme [1] copies the styling of > > > > > > the > > > > > > Open > > > > > > vSwitch website. Start using this, with fallbacks for users > > > > > > who > > > > > > do > > > > > > not > > > > > > have the package installed. > > > > > > > > > > > > This extends support for building docs to users of Sphinx 1.2 > > > > > > as > > > > > > the > > > > > > previous theme - bizstyle - was only available in 1.3+. > > > > > > > > > > Oops - forgot [1]. > > > > > > > > > > [1] https://pypi.python.org/pypi/ovs-sphinx-theme > > > > > > > > > > Stephen > > > > > > > > > > > Signed-off-by: Stephen Finucane <stephen@that.guru> > > > > > > > > Thanks, I added the footnote and pushed this to master. > > > > > > ...and I've updated the readthedocs.org config to use > > > Documentation/requirements.txt. Looks good to me. > > > > I've noticed that when I run "make htmldocs", I always get this > > warning: > > Cannot find 'ovs_sphinx' package. Falling back to default > > theme. > > Is that expected? > > Yes, I have a fallback inserted [1] so that people who don't want to > install anything non-apt/dnf packages can still build the docs locally. > You can get rid of this package by installing the requirements locally. > > $ sudo pip install -r Documentation/requirements.txt > $ make htmldocs > > ...which is what docs.openvswitch.org does now. The building docs page > [2] should probably be updated to reflect this. > > [1] https://github.com/openvswitch/ovs/blob/e25d4af1e690d1091089aefb5b9 > fde31825252d4/Documentation/conf.py#L25-L27 > [2] http://docs.openvswitch.org/en/latest/intro/install/documentation/ Oh wow, I wouldn't have guessed that the theme was kept in some central out-of-tree place. Anyway, I've now installed it locally, thanks.
On 4 January 2017 at 01:03, Stephen Finucane <stephen@that.guru> wrote: > On Tue, 2017-01-03 at 21:33 +0000, Stephen Finucane wrote: >> The recently published 'ovs' theme [1] copies the styling of the Open >> vSwitch website. Start using this, with fallbacks for users who do >> not >> have the package installed. >> >> This extends support for building docs to users of Sphinx 1.2 as the >> previous theme - bizstyle - was only available in 1.3+. > > Oops - forgot [1]. > > [1] https://pypi.python.org/pypi/ovs-sphinx-theme Looks good! One minor nit - on the main OVS website, the logo links to the main website; on the docs page, it links to the docs home page. Is there a way to make this more consistent?
On Wed, 2017-01-04 at 10:32 -0800, Joe Stringer wrote: > On 4 January 2017 at 01:03, Stephen Finucane <stephen@that.guru> > wrote: > > On Tue, 2017-01-03 at 21:33 +0000, Stephen Finucane wrote: > > > The recently published 'ovs' theme [1] copies the styling of the > > > Open > > > vSwitch website. Start using this, with fallbacks for users who > > > do > > > not > > > have the package installed. > > > > > > This extends support for building docs to users of Sphinx 1.2 as > > > the > > > previous theme - bizstyle - was only available in 1.3+. > > > > Oops - forgot [1]. > > > > [1] https://pypi.python.org/pypi/ovs-sphinx-theme > > Looks good! > > One minor nit - on the main OVS website, the logo links to the main > website; on the docs page, it links to the docs home page. Is there a > way to make this more consistent? Cheers :) I've pushed an updated version that resolves this (along with some funky styling of the logo when viewing on a mobile device). Should see it soon as the docs are rebuilt. Stephen
diff --git a/Documentation/conf.py b/Documentation/conf.py index 63f5877..c0b68c1 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -19,12 +19,18 @@ # import os # import sys # sys.path.insert(0, os.path.abspath('.')) +try: + import ovs_sphinx_theme + use_ovs_theme = True +except ImportError: + print("Cannot find 'ovs_sphinx' package. Falling back to default theme.") + use_ovs_theme = False # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. # -# needs_sphinx = '1.0' +needs_sphinx = '1.2' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -102,7 +108,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +# pygments_style = 'friendly' # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] @@ -119,7 +125,10 @@ todo_include_todos = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'bizstyle' +if use_ovs_theme: + html_theme = 'ovs' +else: + html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -128,7 +137,10 @@ html_theme = 'bizstyle' # html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] +if use_ovs_theme: + html_theme_path = [ovs_sphinx_theme.get_theme_dir()] +else: + html_theme_path = [] # The name for this set of Sphinx documents. # "<project> v<release> documentation" by default. diff --git a/Documentation/requirements.txt b/Documentation/requirements.txt index 354d3d0..fcc02fd 100644 --- a/Documentation/requirements.txt +++ b/Documentation/requirements.txt @@ -1 +1,2 @@ -sphinx>=1.3 +sphinx>=1.2,<2.0 +ovs_sphinx_theme>=1.0,<1.1
The recently published 'ovs' theme [1] copies the styling of the Open vSwitch website. Start using this, with fallbacks for users who do not have the package installed. This extends support for building docs to users of Sphinx 1.2 as the previous theme - bizstyle - was only available in 1.3+. Signed-off-by: Stephen Finucane <stephen@that.guru> --- Documentation/conf.py | 20 ++++++++++++++++---- Documentation/requirements.txt | 3 ++- 2 files changed, 18 insertions(+), 5 deletions(-)