Re: [ovs-dev] [PATCH] docs: Update version numbers in doc config.

[Ben Pfaff]

On Wed, Apr 12, 2017 at 11:05:44AM -0400, Russell Bryant wrote:
> On Wed, Apr 12, 2017 at 9:12 AM, Stephen Finucane  wrote:
> > I realized that about 10 minutes ago after diving further into the git
> > history of NEWS :) Why '.90' , out of curiosity?
> 
> It predates my involvement, but I think it's roughly:
> 
> 2.7.90 === much more than 2.7.0, but not quite 2.8.0

Yes, that's right.  Other projects do it differently, but this seems to
work OK for OVS, so far.
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Update version numbers in doc config.

[Russell Bryant]

On Wed, Apr 12, 2017 at 9:12 AM, Stephen Finucane  wrote:
> On Wed, 2017-04-12 at 08:58 -0400, Russell Bryant wrote:
>> On Wed, Apr 12, 2017 at 7:29 AM, Stephen Finucane 
>> wrote:
>> > On Tue, 2017-04-11 at 13:15 -0400, Russell Bryant wrote:
>> > > Update the version numbers in the documentation config to reflect
>> > > 2.7.90
>> > > instead of 2.6.0.
>> > >
>> > > This patch also updates the build system to automatically update
>> > > this
>> > > file.
>> > > conf.py is now a generated file from conf.py.in.  We still
>> > > include
>> > > conf.py
>> > > in the tree because it's needed for the docs to be automatically
>> > > generated
>> > > for docs.openvswitch.org.
>> > >
>> > > Signed-off-by: Russell Bryant 
>> >
>> > Looks OK, but how would we prevent this getting out of date? If
>> > we're
>> > going to include PATCH information, I imagine this would need to be
>> > updated as part of every commit?
>>
>> It doesn't change with every commit.  ".90" is fixed.  "2.7.90" is
>> the
>> version OVS uses for the master branch that will eventually become
>> 2.8.
>
> I realized that about 10 minutes ago after diving further into the git
> history of NEWS :) Why '.90' , out of curiosity?

It predates my involvement, but I think it's roughly:

2.7.90 === much more than 2.7.0, but not quite 2.8.0

>> In terms of keeping it up to date, conf.py is going to show a change
>> as soon as the version changes, but it should only be when a new
>> branch gets created, or after a point release is made from a release
>> branch.
>
> Gotcha.
>
>> > Seeing as a more generic version of this information is already
>> > available in 'NEWS', I imagine we could just parse that instead.
>> > Lemme
>> > draft something quickly and see what you think.
>>
>> Cool, I'll take a look.
>
> Given the above, what I've done works but it likely unnecessary. Unless
> we want to update the version in real time (by parsing git logs using
> dulwich or similar), this solution is probably more consistent with
> OVS' build system. As such:
>
> Acked-by: Stephen Finucane 
>
> Cheers :)
> Stephen

Thanks for the detailed review and feedback!  I'll apply this approach, then.

-- 
Russell Bryant
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Update version numbers in doc config.

[Stephen Finucane]

On Wed, 2017-04-12 at 08:58 -0400, Russell Bryant wrote:
> On Wed, Apr 12, 2017 at 7:29 AM, Stephen Finucane 
> wrote:
> > On Tue, 2017-04-11 at 13:15 -0400, Russell Bryant wrote:
> > > Update the version numbers in the documentation config to reflect
> > > 2.7.90
> > > instead of 2.6.0.
> > > 
> > > This patch also updates the build system to automatically update
> > > this
> > > file.
> > > conf.py is now a generated file from conf.py.in.  We still
> > > include
> > > conf.py
> > > in the tree because it's needed for the docs to be automatically
> > > generated
> > > for docs.openvswitch.org.
> > > 
> > > Signed-off-by: Russell Bryant 
> > 
> > Looks OK, but how would we prevent this getting out of date? If
> > we're
> > going to include PATCH information, I imagine this would need to be
> > updated as part of every commit?
> 
> It doesn't change with every commit.  ".90" is fixed.  "2.7.90" is
> the
> version OVS uses for the master branch that will eventually become
> 2.8.

I realized that about 10 minutes ago after diving further into the git
history of NEWS :) Why '.90' , out of curiosity?

> In terms of keeping it up to date, conf.py is going to show a change
> as soon as the version changes, but it should only be when a new
> branch gets created, or after a point release is made from a release
> branch.

Gotcha.

> > Seeing as a more generic version of this information is already
> > available in 'NEWS', I imagine we could just parse that instead.
> > Lemme
> > draft something quickly and see what you think.
> 
> Cool, I'll take a look.

Given the above, what I've done works but it likely unnecessary. Unless
we want to update the version in real time (by parsing git logs using
dulwich or similar), this solution is probably more consistent with
OVS' build system. As such:

Acked-by: Stephen Finucane 

Cheers :)
Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Update version numbers in doc config.

[Russell Bryant]

On Wed, Apr 12, 2017 at 7:29 AM, Stephen Finucane  wrote:
> On Tue, 2017-04-11 at 13:15 -0400, Russell Bryant wrote:
>> Update the version numbers in the documentation config to reflect
>> 2.7.90
>> instead of 2.6.0.
>>
>> This patch also updates the build system to automatically update this
>> file.
>> conf.py is now a generated file from conf.py.in.  We still include
>> conf.py
>> in the tree because it's needed for the docs to be automatically
>> generated
>> for docs.openvswitch.org.
>>
>> Signed-off-by: Russell Bryant 
>
> Looks OK, but how would we prevent this getting out of date? If we're
> going to include PATCH information, I imagine this would need to be
> updated as part of every commit?

It doesn't change with every commit.  ".90" is fixed.  "2.7.90" is the
version OVS uses for the master branch that will eventually become
2.8.

In terms of keeping it up to date, conf.py is going to show a change
as soon as the version changes, but it should only be when a new
branch gets created, or after a point release is made from a release
branch.

> Seeing as a more generic version of this information is already
> available in 'NEWS', I imagine we could just parse that instead. Lemme
> draft something quickly and see what you think.

Cool, I'll take a look.

-- 
Russell Bryant
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Update version numbers in doc config.

[Stephen Finucane]

On Tue, 2017-04-11 at 13:15 -0400, Russell Bryant wrote:
> Update the version numbers in the documentation config to reflect
> 2.7.90
> instead of 2.6.0.
> 
> This patch also updates the build system to automatically update this
> file.
> conf.py is now a generated file from conf.py.in.  We still include
> conf.py
> in the tree because it's needed for the docs to be automatically
> generated
> for docs.openvswitch.org.
> 
> Signed-off-by: Russell Bryant 

Looks OK, but how would we prevent this getting out of date? If we're
going to include PATCH information, I imagine this would need to be
updated as part of every commit?

Seeing as a more generic version of this information is already
available in 'NEWS', I imagine we could just parse that instead. Lemme
draft something quickly and see what you think.

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH] docs: Update version numbers in doc config.

[Russell Bryant]

Update the version numbers in the documentation config to reflect 2.7.90
instead of 2.6.0.

This patch also updates the build system to automatically update this file.
conf.py is now a generated file from conf.py.in.  We still include conf.py
in the tree because it's needed for the docs to be automatically generated
for docs.openvswitch.org.

Signed-off-by: Russell Bryant 
---
 Documentation/automake.mk |  10 ++
 Documentation/conf.py |   5 +-
 Documentation/conf.py.in  | 349 ++
 3 files changed, 362 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/conf.py.in

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 1fd452b..ed12ad0 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -3,6 +3,7 @@ DOC_SOURCE = \
Documentation/_static/logo.png \
Documentation/_static/overview.png \
Documentation/conf.py \
+   Documentation/conf.py.in \
Documentation/index.rst \
Documentation/contents.rst \
Documentation/intro/index.rst \
@@ -123,6 +124,15 @@ clean-docs:
rm -rf $(SPHINXBUILDDIR)/html
rm -rf $(SPHINXBUILDDIR)/linkcheck
 CLEAN_LOCAL += clean-docs
+
+ALL_LOCAL += $(srcdir)/Documentation/conf.py
+$(srcdir)/Documentation/conf.py: $(srcdir)/Documentation/conf.py.in
+   $(AM_V_GEN)($(ro_shell) && sed -e 's,[@]VERSION[@],$(VERSION),g' \
+   -e 's,[@]OVS_MAJOR[@],$(shell echo $(VERSION) | cut -f1 -d.),g' 
\
+   -e 's,[@]OVS_MINOR[@],$(shell echo $(VERSION) | cut -f2 
-d.),g') \
+   < $(srcdir)/Documentation/$(@F).in > $(@F).tmp || exit 1; \
+   if cmp -s $(@F).tmp $@; then touch $@; rm $(@F).tmp; else mv $(@F).tmp 
$@; fi
+
 endif
 .PHONY: check-docs
 .PHONY: clean-docs
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 6a924b3..ae672cb 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -1,3 +1,4 @@
+# Generated automatically -- do not modify!-*- buffer-read-only: t -*-
 # -*- coding: utf-8 -*-
 #
 # Open vSwitch documentation build configuration file, created by
@@ -63,9 +64,9 @@ author = u'The Open vSwitch Development Community'
 # built documents.
 #
 # The short X.Y version.
-version = u'2.6'
+version = u'2.7'
 # The full version, including alpha/beta/rc tags.
-release = u'2.6.0'
+release = u'2.7.90'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in
new file mode 100644
index 000..5ed7006
--- /dev/null
+++ b/Documentation/conf.py.in
@@ -0,0 +1,349 @@
+# -*- coding: utf-8 -*-
+#
+# Open vSwitch documentation build configuration file, created by
+# sphinx-quickstart on Fri Sep 30 09:57:36 2016.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# 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.1'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'contents'
+
+# General information about the project.
+project = u'Open vSwitch'
+copyright = u'2016, The Open vSwitch Development Community'
+author = u'The Open vSwitch Development Community'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'@OVS_MAJOR@.@OVS_MINOR@'
+# The full version, including alpha/beta/rc tags.
+release = u'@VERSION@'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+#