[ovs-dev] Sphinx conversion questions

[Stephen Finucane]

Howdy,

I'm trying to work through the Sphinx integration, but I have two issues 
that I need to resolve before progressing. I'd like input from 
maintainers on this.

Firstly, there is a lot of cross-referencing that I need to untangle. 
Before doing even more of that, I'd like some input on what docs should 
be retained at the root directory and which ones can be moved. I've 
given my keep/move list below. Before I continue, does anyone disagree 
with that and, if so, what do you propose we do instead?

In addition, I'm trying to figure out how we can integrate this into the 
website. I see two options:

- We deploy docs using GitHub pages and the existing URL (/support)

   We would create a Sphinx theme to retain consistent styling and 
identity across the site. I did some work on this yesterday evening, but 
ended up getting sidetracked, heh [1]. This has the advantage of not 
needing any new CNAME files, subdomains etc., but means we'd have to do 
things like versioning [2] manually.

- We deploy to a subdomain like 'docs.openvswitch.org' and actually host 
on ReadTheDocs [3] or similar

   We would start with a stock theme and possibly look at creating one 
that matches the visual identity of the main site at a later date (see 
the OpenStack Docs [4] vs. OpenStack main site [5]). ReadTheDocs would 
provide automatic uploading, versioning, etc., preventing the need to 
manually update the site each time we get a doc-related patch. There is, 
however, an optional cost associated with this (*). I noticed that the 
mailing list archives seem to have been moved to 'mail.openvswitch.org' 
over the weekend, for example.

I prefer the second option, but I'm used to this workflow and therefore 
biased.

Thoughts?

Cheers,
Stephen

(*) I have less than zero say in this, but if we end up using 
ReadTheDocs then I would request that the project look at the corporate 
options offered (https://readthedocs.com/services/#open-source-support). 
ReadTheDocs do a fantastic job for the open source community and, as 
Heartbleed and the subsequent Core Infrastructure Initiative showed us, 
open source tools and sites always need the cash to keep doing what they 
do.

[1] https://github.com/openvswitch/openvswitch.github.io/pull/28
[2] https://patchwork.readthedocs.io/en/v1.1.2/
[3] https://readthedocs.org/
[4] http://docs.openstack.org/
[5] https://openstack.org/

---

Here's the list of docs I think
we should retain in the top-level directory:

- AUTHORS (*)
- CodingStyle.rst  (**)
- CONTRIBUTING.rst
- COPYING
- DocumentationStyle.rst (**)
- MAINTAINERS.rst
- NEWS
- NOTICE
- README.rst
- REPORTING-BUGS.rst
- SECURITY.rst

By extension, this means these documents will be moved:

- DESIGN.rst
- FAQ.rst
- INSTALL.Debian.rst
- INSTALL.Docker.rst
- INSTALL.DPDK-ADVANCED.rst
- INSTALL.DPDK.rst
- INSTALL.Fedora.rst
- INSTALL.KVM.rst
- INSTALL.Libvirt.rst
- INSTALL.NetBSD.rst
- INSTALL.RHEL.rst
- INSTALL.rst
- INSTALL.SELinux.rst
- INSTALL.SSL.rst
- INSTALL.userspace.rst
- INSTALL.Windows.rst
- INSTALL.XenServer.rst
- IntegrationGuide.rst
- PORTING.rst
- README-lisp.rst
- README-native-tunneling.rst
- WHY-OVS.rst

(*) I'd like to convert this to rST too, but I don't know how to rework 
the script in 'debian/automake.mk'. Some help would be appreciated here.

(**) I'd like to uppercase these, purely for consistency's sake