| Message ID | 1488513702-100140-1-git-send-email-dlu998@gmail.com |
|---|---|
| State | Changes Requested |
| Headers | show |
On Thu, 2017-03-02 at 20:01 -0800, Darrell Ball wrote: > Some code-block directives are not understood using > Trusty (I was using 14.04.1 when the issue was found) > default package versions, which blocks the build. > > An error example: > writing output... [100%] topics/language-bindings > Warning, treated as error: > /home/dball/ovs/Documentation/topics/language-bindings.rst:39: > WARNING: Pygments lexer name u'shell' is not known > > 14.04.1 has Sphinx 1.2.2 and Pygments 1.6. > > I expect Trusty to still be widely used, so we > should be able to build ovs with it. > > requirements.rst indicates only: > sphinx>=1.2,<2.0 > ovs_sphinx_theme>=1.0,<1.1 > > Fixes: f150a8bafbf2 ("doc: Document various language bindings") > Suggested-by: Daniele Di Proietto <diproiettod@vmware.com> > Signed-off-by: Darrell Ball <dlu998@gmail.com> > CC: Stephen Finucane <stephen@that.guru> This all looks fine to me. I'm not sure if 14.04 is a valid target still (for development at least), but these changes are small enough and the requirements *do* state 1.2 as the minimum. As such: Acked-by: Stephen Finucane <stephen@that.guru> Could you also submit a modification to the documentation style guide as a follow up, noting the need to validate docs against the minimum supported version? Cheers, Stephen
On Tue, Mar 7, 2017 at 5:31 AM, Stephen Finucane <stephen@that.guru> wrote: > On Thu, 2017-03-02 at 20:01 -0800, Darrell Ball wrote: > > Some code-block directives are not understood using > > Trusty (I was using 14.04.1 when the issue was found) > > default package versions, which blocks the build. > > > > An error example: > > writing output... [100%] topics/language-bindings > > Warning, treated as error: > > /home/dball/ovs/Documentation/topics/language-bindings.rst:39: > > WARNING: Pygments lexer name u'shell' is not known > > > > 14.04.1 has Sphinx 1.2.2 and Pygments 1.6. > > > > I expect Trusty to still be widely used, so we > > should be able to build ovs with it. > > > > requirements.rst indicates only: > > sphinx>=1.2,<2.0 > > ovs_sphinx_theme>=1.0,<1.1 > > > > Fixes: f150a8bafbf2 ("doc: Document various language bindings") > > Suggested-by: Daniele Di Proietto <diproiettod@vmware.com> > > Signed-off-by: Darrell Ball <dlu998@gmail.com> > > CC: Stephen Finucane <stephen@that.guru> > > This all looks fine to me. I'm not sure if 14.04 is a valid > target still (for development at least), but these changes are small > enough and the requirements *do* state 1.2 as the minimum. As such: > > Acked-by: Stephen Finucane <stephen@that.guru> > > Could you also submit a modification to the documentation style guide > as a follow up, noting the need to validate docs against the minimum > supported version? > Maybe we should set up a tox environment that builds the docs using the minimum supported version of sphinx. That would make it easy on everyone to test.
On Tue, 2017-03-07 at 08:21 -0500, Russell Bryant wrote: > > > On Tue, Mar 7, 2017 at 5:31 AM, Stephen Finucane <stephen@that.guru> > wrote: > > On Thu, 2017-03-02 at 20:01 -0800, Darrell Ball wrote: > > > Some code-block directives are not understood using > > > Trusty (I was using 14.04.1 when the issue was found) > > > default package versions, which blocks the build. > > > > > > An error example: > > > writing output... [100%] topics/language-bindings > > > Warning, treated as error: > > > /home/dball/ovs/Documentation/topics/language-bindings.rst:39: > > > WARNING: Pygments lexer name u'shell' is not known > > > > > > 14.04.1 has Sphinx 1.2.2 and Pygments 1.6. > > > > > > I expect Trusty to still be widely used, so we > > > should be able to build ovs with it. > > > > > > requirements.rst indicates only: > > > sphinx>=1.2,<2.0 > > > ovs_sphinx_theme>=1.0,<1.1 > > > > > > Fixes: f150a8bafbf2 ("doc: Document various language bindings") > > > Suggested-by: Daniele Di Proietto <diproiettod@vmware.com> > > > Signed-off-by: Darrell Ball <dlu998@gmail.com> > > > CC: Stephen Finucane <stephen@that.guru> > > > > This all looks fine to me. I'm not sure if 14.04 is a valid > > target still (for development at least), but these changes are > > small > > enough and the requirements *do* state 1.2 as the minimum. As such: > > > > Acked-by: Stephen Finucane <stephen@that.guru> > > > > Could you also submit a modification to the documentation style > > guide > > as a follow up, noting the need to validate docs against the > > minimum > > supported version? > > Maybe we should set up a tox environment that builds the docs using > the minimum supported version of sphinx. That would make it easy on > everyone to test. This sounds good to me - I'd have it done already only I wasn't sure if you'd want a tox file in a non-Python project :) I can draft that shortly if you're OK with it. I'd still like to update the documentation guide in any case, even if only to reference the tox option. Stephen PS: This also sounds like something that could be automatically tested. If only some folks were working on a tool to automatically test mailing list patches... https://speakerdeck.com/stephenfin/mailing-list-meet-ci
On Tue, Mar 07, 2017 at 05:01:06PM +0000, Stephen Finucane wrote: > PS: This also sounds like something that could be automatically tested. > If only some folks were working on a tool to automatically test mailing > list patches... > > https://speakerdeck.com/stephenfin/mailing-list-meet-ci More automatic tests are (almost) always better. Is this something that's ready for us to try out, or should we wait until it's more mature?
On Thu, Mar 02, 2017 at 08:01:42PM -0800, Darrell Ball wrote: > Some code-block directives are not understood using > Trusty (I was using 14.04.1 when the issue was found) > default package versions, which blocks the build. > > An error example: > writing output... [100%] topics/language-bindings > Warning, treated as error: > /home/dball/ovs/Documentation/topics/language-bindings.rst:39: > WARNING: Pygments lexer name u'shell' is not known > > 14.04.1 has Sphinx 1.2.2 and Pygments 1.6. > > I expect Trusty to still be widely used, so we > should be able to build ovs with it. > > requirements.rst indicates only: > sphinx>=1.2,<2.0 > ovs_sphinx_theme>=1.0,<1.1 > > Fixes: f150a8bafbf2 ("doc: Document various language bindings") > Suggested-by: Daniele Di Proietto <diproiettod@vmware.com> > Signed-off-by: Darrell Ball <dlu998@gmail.com> > CC: Stephen Finucane <stephen@that.guru> I was pointed to apply this but it adds an error for me: /home/blp/nicira/ovs/Documentation/intro/install/windows.rst:585: WARNING: Could not lex literal_block as "ps1". Highlighting skipped. I'm using Sphinx 1.4.9.
On Tue, 2017-03-07 at 11:01 -0800, Ben Pfaff wrote: > On Tue, Mar 07, 2017 at 05:01:06PM +0000, Stephen Finucane wrote: > > PS: This also sounds like something that could be automatically > > tested. > > If only some folks were working on a tool to automatically test > > mailing > > list patches... > > > > https://speakerdeck.com/stephenfin/mailing-list-meet-ci > > More automatic tests are (almost) always better. Is this something > that's ready for us to try out, or should we wait until it's more > mature? Not quite yet. I'll let you know when it is though. Stephen
On 3/7/17, 3:03 PM, "ovs-dev-bounces@openvswitch.org on behalf of Ben Pfaff" <ovs-dev-bounces@openvswitch.org on behalf of blp@ovn.org> wrote:
On Thu, Mar 02, 2017 at 08:01:42PM -0800, Darrell Ball wrote:
> Some code-block directives are not understood using
> Trusty (I was using 14.04.1 when the issue was found)
> default package versions, which blocks the build.
>
> An error example:
> writing output... [100%] topics/language-bindings
> Warning, treated as error:
> /home/dball/ovs/Documentation/topics/language-bindings.rst:39:
> WARNING: Pygments lexer name u'shell' is not known
>
> 14.04.1 has Sphinx 1.2.2 and Pygments 1.6.
>
> I expect Trusty to still be widely used, so we
> should be able to build ovs with it.
>
> requirements.rst indicates only:
> sphinx>=1.2,<2.0
> ovs_sphinx_theme>=1.0,<1.1
>
> Fixes: f150a8bafbf2 ("doc: Document various language bindings")
> Suggested-by: Daniele Di Proietto <diproiettod@vmware.com>
> Signed-off-by: Darrell Ball <dlu998@gmail.com>
> CC: Stephen Finucane <stephen@that.guru>
I was pointed to apply this but it adds an error for me:
/home/blp/nicira/ovs/Documentation/intro/install/windows.rst:585: WARNING: Could not lex literal_block as "ps1". Highlighting skipped.
I'm using Sphinx 1.4.9.
yikes
That is coming from Pygments, afaik.
That seems to imply new versions of Pygments are not backward compatible;
ps1 lexer worked with sphinx 1.3.6 and 1.2.2.
Maybe we can use a safe legacy lexer specification like “bat” in these cases. The
highlighting is very similar with “bat” and one would hope “bat” should
remain backward compatible for an extended timeframe.
It is more important that the build always works, rather than trying to achieve
slight differences in highlighting for different code/script types.
Does that seem reasonable ?
Does “bat” work in your environment ?
_______________________________________________
dev mailing list
dev@openvswitch.org
https://urldefense.proofpoint.com/v2/url?u=https-3A__mail.openvswitch.org_mailman_listinfo_ovs-2Ddev&d=DwICAg&c=uilaK90D4TOVoH58JNXRgQ&r=BVhFA09CGX7JQ5Ih-uZnsw&m=ivjgO8tI5Ru_nAC0gnDJYjgmSGcJlgrOvps6ra4rEDw&s=mTP9O7IELdpPzUvrKhBrBFrjv96XVW76WVkHGtMYFNU&e=
On 3/8/17, 1:30 PM, "Ben Pfaff" <blp@ovn.org> wrote:
On Wed, Mar 08, 2017 at 08:58:05PM +0000, Darrell Ball wrote:
>
>
> On 3/7/17, 3:03 PM, "ovs-dev-bounces@openvswitch.org on behalf of Ben Pfaff" <ovs-dev-bounces@openvswitch.org on behalf of blp@ovn.org> wrote:
>
> On Thu, Mar 02, 2017 at 08:01:42PM -0800, Darrell Ball wrote:
> > Some code-block directives are not understood using
> > Trusty (I was using 14.04.1 when the issue was found)
> > default package versions, which blocks the build.
> >
> > An error example:
> > writing output... [100%] topics/language-bindings
> > Warning, treated as error:
> > /home/dball/ovs/Documentation/topics/language-bindings.rst:39:
> > WARNING: Pygments lexer name u'shell' is not known
> >
> > 14.04.1 has Sphinx 1.2.2 and Pygments 1.6.
> >
> > I expect Trusty to still be widely used, so we
> > should be able to build ovs with it.
> >
> > requirements.rst indicates only:
> > sphinx>=1.2,<2.0
> > ovs_sphinx_theme>=1.0,<1.1
> >
> > Fixes: f150a8bafbf2 ("doc: Document various language bindings")
> > Suggested-by: Daniele Di Proietto <diproiettod@vmware.com>
> > Signed-off-by: Darrell Ball <dlu998@gmail.com>
> > CC: Stephen Finucane <stephen@that.guru>
>
> I was pointed to apply this but it adds an error for me:
>
> /home/blp/nicira/ovs/Documentation/intro/install/windows.rst:585: WARNING: Could not lex literal_block as "ps1". Highlighting skipped.
>
> I'm using Sphinx 1.4.9.
>
> yikes
> That is coming from Pygments, afaik.
> That seems to imply new versions of Pygments are not backward compatible;
> ps1 lexer worked with sphinx 1.3.6 and 1.2.2.
>
> Maybe we can use a safe legacy lexer specification like “bat” in these cases. The
> highlighting is very similar with “bat” and one would hope “bat” should
> remain backward compatible for an extended timeframe.
> It is more important that the build always works, rather than trying to achieve
> slight differences in highlighting for different code/script types.
>
> Does that seem reasonable ?
> Does “bat” work in your environment ?
Applying the following, it builds fine:
diff --git a/Documentation/intro/install/windows.rst b/Documentation/intro/install/windows.rst
index caa9f40e0a41..879e0dcf1680 100644
--- a/Documentation/intro/install/windows.rst
+++ b/Documentation/intro/install/windows.rst
@@ -582,7 +582,7 @@ found at technet_.
For example, to set up a switch team combined from ``Ethernet0 2`` and
``Ethernet1 2`` named ``external``:
-.. code-block:: ps1con
+.. code-block:: bat
PS > Get-NetAdapter
Name InterfaceDescription
Will you submit a v2?
Thanks for verifying.
I will submit a V2.
Darrell
Thanks,
Ben.
diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst index ea41a07..184f728 100644 --- a/Documentation/internals/contributing/documentation-style.rst +++ b/Documentation/internals/contributing/documentation-style.rst @@ -259,7 +259,7 @@ Figures and Other Media - All images should be in PNG format and compressed where possible. For PNG files, use OptiPNG and AdvanceCOMP's ``advpng``: - .. code-block:: shell + .. code-block:: bash $ optipng -o7 -zm1-9 -i0 -strip all <path_to_png> $ advpng -z4 <path_to_png> diff --git a/Documentation/intro/install/windows.rst b/Documentation/intro/install/windows.rst index caa9f40..6cc8a6b 100644 --- a/Documentation/intro/install/windows.rst +++ b/Documentation/intro/install/windows.rst @@ -225,7 +225,7 @@ building on Linux, FreeBSD, or NetBSD. all MinGW sessions and then run the below command from MSVC developers command prompt.: - .. code-block:: doscon + .. code-block:: bat > mingw-get upgrade msys-core-bin=1.0.17-1 @@ -276,7 +276,7 @@ Now run ``./uninstall.cmd`` to remove the old extension. Once complete, run turn on ``TESTSIGNING`` boot option or 'Disable Driver Signature Enforcement' during boot. The following commands can be used: -.. code-block:: doscon +.. code-block:: bat > bcdedit /set LOADOPTIONS DISABLE_INTEGRITY_CHECKS > bcdedit /set TESTSIGNING ON @@ -294,7 +294,7 @@ to work (covered later). The command to create a new switch named 'OVS-Extended-Switch' using a physical NIC named 'Ethernet 1' is: -.. code-block:: ps1con +.. code-block:: ps1 PS > New-VMSwitch "OVS-Extended-Switch" -NetAdapterName "Ethernet 1" @@ -307,7 +307,7 @@ In the properties of any switch, you should should now see "Open vSwitch Extension" under 'Extensions'. Click the check box to enable the extension. An alternative way to do the same is to run the following command: -.. code-block:: ps1con +.. code-block:: ps1 PS > Enable-VMSwitchExtension "Open vSwitch Extension" OVS-Extended-Switch @@ -330,7 +330,7 @@ database, ovsdb-server. Each machine on which Open vSwitch is installed should run its own copy of ovsdb-server. Before ovsdb-server itself can be started, configure a database that it can use: -.. code-block:: doscon +.. code-block:: bat > ovsdb-tool create C:\openvswitch\etc\openvswitch\conf.db \ C:\openvswitch\usr\share\openvswitch\vswitch.ovsschema @@ -338,7 +338,7 @@ configure a database that it can use: Configure ovsdb-server to use database created above and to listen on a Unix domain socket: -.. code-block:: doscon +.. code-block:: bat > ovsdb-server -vfile:info --remote=punix:db.sock --log-file \ --pidfile --detach @@ -351,7 +351,7 @@ Initialize the database using ovs-vsctl. This is only necessary the first time after you create the database with ovsdb-tool, though running it at any time is harmless: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl --no-wait init @@ -359,14 +359,14 @@ harmless: If you would later like to terminate the started ovsdb-server, run: - .. code-block:: doscon + .. code-block:: bat > ovs-appctl -t ovsdb-server exit Start the main Open vSwitch daemon, telling it to connect to the same Unix domain socket: -.. code-block:: doscon +.. code-block:: bat > ovs-vswitchd -vfile:info --log-file --pidfile --detach @@ -374,7 +374,7 @@ domain socket: If you would like to terminate the started ovs-vswitchd, run: - .. code-block:: doscon + .. code-block:: bat > ovs-appctl exit @@ -394,7 +394,7 @@ Add bridges Let's start by creating an integration bridge, ``br-int`` and a PIF bridge, ``br-pif``: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl add-br br-int > ovs-vsctl add-br br-pif @@ -408,7 +408,7 @@ Let's start by creating an integration bridge, ``br-int`` and a PIF bridge, Validate that ports are added by dumping from both ovs-dpctl and ovs-vsctl: -.. code-block:: doscon +.. code-block:: bat > ovs-dpctl show system@ovs-system: @@ -457,7 +457,7 @@ enable them and set the corresponding values to it to make them IP-able. As a whole example, if we issue the following in a powershell console: -.. code-block:: ps1con +.. code-block:: ps1 PS > Get-NetAdapter | select Name,InterfaceDescription Name InterfaceDescription @@ -476,13 +476,13 @@ We can see that we have a switch(external) created upon adapter name 'Ethernet0' with the internal ports under name 'br-pif' and 'br-int'. Thus resulting into the following ovs-vsctl commands: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl add-port br-pif Ethernet0 Dumping the ports should show the additional ports that were just added: -.. code-block:: doscon +.. code-block:: bat > ovs-dpctl show system@ovs-system: @@ -525,7 +525,7 @@ is being addressed. After assigning the name ``ovs-port-a``, the VIF is connected back to the Hyper-V switch with name ``OVS-HV-Switch``, which is assumed to be the Hyper-V switch with OVS extension enabled.: -.. code-block:: ps1con +.. code-block:: ps1 PS > import-module .\datapath-windows\misc\OVS.psm1 PS > $vnic = Get-VMNetworkAdapter <Name of the VM> @@ -536,13 +536,13 @@ assumed to be the Hyper-V switch with OVS extension enabled.: Next, add the VIFs to ``br-int``: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl add-port br-int ovs-port-a Dumping the ports should show the additional ports that were just added: -.. code-block:: doscon +.. code-block:: bat > ovs-dpctl show system@ovs-system: @@ -582,7 +582,7 @@ found at technet_. For example, to set up a switch team combined from ``Ethernet0 2`` and ``Ethernet1 2`` named ``external``: -.. code-block:: ps1con +.. code-block:: ps1 PS > Get-NetAdapter Name InterfaceDescription @@ -602,7 +602,7 @@ For example, to set up a switch team combined from ``Ethernet0 2`` and This will result in a new adapter bound to the host called ``external``: -.. code-block:: ps1con +.. code-block:: ps1 PS > Get-NetAdapter Name InterfaceDescription @@ -617,7 +617,7 @@ This will result in a new adapter bound to the host called ``external``: Next we will set up the Hyper-V VMSwitch on the new adapter ``external``: -.. code-block:: ps1con +.. code-block:: ps1 PS > New-VMSwitch -Name external -NetAdapterName external \ -AllowManagementOS $false @@ -628,7 +628,7 @@ Under OVS the adapters under the team ``external``, ``Ethernet0 2`` and The following example shows how the bridges look with the NICs being separated: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl show 6cd9481b-c249-4ee3-8692-97b399dd29d8 @@ -653,7 +653,7 @@ Switch VLAN tagging along with patch ports between ``br-int`` and ``br-pif`` is used to configure VLAN tagging functionality between two VMs on different Hyper-Vs. To start, add a patch port from ``br-int`` to ``br-pif``: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl add-port br-int patch-to-pif > ovs-vsctl set interface patch-to-pif type=patch \ @@ -661,7 +661,7 @@ Hyper-Vs. To start, add a patch port from ``br-int`` to ``br-pif``: Add a patch port from ``br-pif`` to ``br-int``: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl add-port br-pif patch-to-int > ovs-vsctl set interface patch-to-int type=patch \ @@ -669,7 +669,7 @@ Add a patch port from ``br-pif`` to ``br-int``: Re-Add the VIF ports with the VLAN tag: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl add-port br-int ovs-port-a tag=900 > ovs-vsctl add-port br-int ovs-port-b tag=900 @@ -681,7 +681,7 @@ The Windows Open vSwitch implementation support VXLAN and STT tunnels. To add tunnels. For example, first add the tunnel port between 172.168.201.101 <-> 172.168.201.102: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl add-port br-int tun-1 > ovs-vsctl set Interface tun-1 type=<port-type> @@ -692,7 +692,7 @@ tunnels. For example, first add the tunnel port between 172.168.201.101 <-> ...and the tunnel port between 172.168.201.101 <-> 172.168.201.105: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl add-port br-int tun-2 > ovs-vsctl set Interface tun-2 type=<port-type> @@ -717,14 +717,14 @@ daemons via ``make install``. To start, create the database: -.. code-block:: doscon +.. code-block:: bat > ovsdb-tool create C:/openvswitch/etc/openvswitch/conf.db \ "C:/openvswitch/usr/share/openvswitch/vswitch.ovsschema" Create the ovsdb-server service and start it: -.. code-block:: doscon +.. code-block:: bat > sc create ovsdb-server \ binpath="C:/openvswitch/usr/sbin/ovsdb-server.exe \ @@ -739,25 +739,25 @@ Create the ovsdb-server service and start it: paths. You can make sure that the correct path has been registered with the Windows services manager by running: - .. code-block:: doscon + .. code-block:: bat > sc qc ovsdb-server Check that the service is healthy by running: -.. code-block:: doscon +.. code-block:: bat > sc query ovsdb-server Initialize the database: -.. code-block:: doscon +.. code-block:: bat > ovs-vsctl --no-wait init Create the ovs-vswitchd service and start it: -.. code-block:: doscon +.. code-block:: bat > sc create ovs-vswitchd \ binpath="C:/openvswitch/usr/sbin/ovs-vswitchd.exe \ @@ -766,13 +766,13 @@ Create the ovs-vswitchd service and start it: Check that the service is healthy by running: -.. code-block:: doscon +.. code-block:: bat > sc query ovs-vswitchd To stop and delete the services, run: -.. code-block:: doscon +.. code-block:: bat > sc stop ovs-vswitchd > sc stop ovsdb-server diff --git a/Documentation/topics/language-bindings.rst b/Documentation/topics/language-bindings.rst index 5114125..ff91bb8 100644 --- a/Documentation/topics/language-bindings.rst +++ b/Documentation/topics/language-bindings.rst @@ -36,7 +36,7 @@ Python The Python bindings are part of the `Open vSwitch package`__. You can install the bindings using ``pip``: -.. code-block:: shell +.. code-block:: bash $ pip install ovs
Some code-block directives are not understood using Trusty (I was using 14.04.1 when the issue was found) default package versions, which blocks the build. An error example: writing output... [100%] topics/language-bindings Warning, treated as error: /home/dball/ovs/Documentation/topics/language-bindings.rst:39: WARNING: Pygments lexer name u'shell' is not known 14.04.1 has Sphinx 1.2.2 and Pygments 1.6. I expect Trusty to still be widely used, so we should be able to build ovs with it. requirements.rst indicates only: sphinx>=1.2,<2.0 ovs_sphinx_theme>=1.0,<1.1 Fixes: f150a8bafbf2 ("doc: Document various language bindings") Suggested-by: Daniele Di Proietto <diproiettod@vmware.com> Signed-off-by: Darrell Ball <dlu998@gmail.com> CC: Stephen Finucane <stephen@that.guru> --- .../internals/contributing/documentation-style.rst | 2 +- Documentation/intro/install/windows.rst | 70 +++++++++++----------- Documentation/topics/language-bindings.rst | 2 +- 3 files changed, 37 insertions(+), 37 deletions(-)