[ovs-dev] [RFC 0/5] Integrate Sphinx documentation generator

Stephen Finucane stephen at that.guru
Wed Oct 5 20:20:03 UTC 2016


On 2016-10-05 17:29, Ben Pfaff wrote:
> On Wed, Oct 05, 2016 at 10:05:50AM +0000, Stephen Finucane wrote:

[snip]

>> 3) Rework docs into a series of guides
>> 
>>    I see the following guides as being helpful
>> 
>>    - Installation guide
>>    - Usage guide
>>    - Contributor guide
>> 
>>    I had a 'testing-guide', but this makes more sense split between 
>> the
>> middle two. Any other guides?
> 
> We probably want to have separate guides for OVS and for OVN, at least
> for installation and usage.

Agreed. I'll scope this out a little further once the basic conversion 
is complete.

>> This would be three separate series so I don't have to do everything 
>> at
>> once. I'd also welcome assistance from anyone who wants to take the 
>> chance
>> to rework some aspect of the docs.
> 
> I can help with some MD->RST.  You mentioned that you've already done 
> it
> for about half the docs and hadn't posted all of those.

I've actually got a good deal more done over the weekend (it didn't stop 
raining) so there's only the below left:

- INSTALL.Fedora.md
- INSTALL.Libvirt.md
- INSTALL.RHEL.md
- INSTALL.SELinux.md
- INSTALL.SSL.md
- tutorial/Tutorial.md
- tutorial/OVN-Tutorial.md
- ovn/CONTAINERS.OpenStack.md
- ovn/OVN-GW-HA.md
- Documentation/OVSDB-replication.md
- Documentation/release-process.md

(I'm also half way through the FAQ, which is crazy long and should 
probable be broken up at some point)

I won't get a chance to work on these until next weekend at the 
earliest, so if you (or anyone) wants to take a look at any of that 
would be helpful.

As far as converting goes, I've found a lot of the Markdown is broken 
meaning pandoc doesn't handle it well. Doing it manually takes as much 
time as fixing the badly parsed text and gives you the chance to 
refactor some stuff.

> Thanks a lot for taking this on!  It's something I've thought of before
> (I was thinking of a DocBook or Texinfo route, although I wasn't really
> satisfied with either of those; Sphinx seems fine), but I've never
> actually taken it on.

No problem. reST is definitely the best choice based on my 
investigations and ties in well with related projects. Hopefully this 
helps lower the entry curve for OVS yet more.

Stephen



More information about the dev mailing list