On Tue, Nov 8, 2016 at 2:09 AM, Stephen Finucane <[email protected]> wrote:
> 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? > The split you've proposed seems reasonable to me. > > 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. > The automatic doc site rebuild has me leaning toward readthedocs.org. -- Russell Bryant _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
