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
_______________________________________________
dev mailing list
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
