[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