Open Stack

Ah I got it, I hadn't really considered how much more likely the
requirements are to change for nailgun and the other components that
should have auto-generated API docs.  Having those build completely
separately matches OpenStack proper too - I'm on board now :)  We can
work out the details over the next few weeks, should be able to wrap
it up no latter than mid January.

I'll get to work next week on updating the blueprint to reflect this approach.

-Christopher

On Thu, Dec 25, 2014 at 6:31 AM, Aleksandra Fedorova
<afedorova at mirantis.com> wrote:
> There are different types of dependencies:
>
> docs dependencies like sphinx, plantuml and so on are rarely changed
> so we can create environment on a slave during slave deployment phase
> and keep it there. But nailgun dependencies for example can be changed
> at any time, thus we need to update the environment every time we
> checkout fuel-web/ repository. Therefore workflow for building just
> docs from rst-files is different from the one where you need to update
> everything before you start.
>
> Also autodocs should be updated and tested on changes into fuel-web
> code, while changes to fuel-docs don't usually touch them.
>
> Thus I think that autodocs belong to the repository they are generated
> from and I'd like to keep them there. That's why I moved objects.rst
> and api_doc.rst into nailgun/docs in [1]
>
> One more thing is that fuel-web is not the only repository which
> produces autodocs. There are autodocs from fuel-main/fuelweb_test repo
> and autodocs from fuel-devops/docs. And I'd like to have the same
> general workflow for all of them.
>
>
> So my idea is that we should keep:
>
> 1) repository fuel-docs with all texts and diagrams, including Fuel
> Developer Guide,
> 2) repository fuel-web/nailgun/docs with nailgun reference,
> 3) repository fuel-main/fuelweb_test/docs with autogenerated system
> tests reference,
> 4) repository fuel-devops/docs with autogenerated fuel-devops reference,
> 5) repository fuel-specs with specifications.
>
> On CI we will build autodocs for every commit into fuel-web, fuel-main
> and fuel-devops. And we will build docs on every commit for fuel-docs
> without additional repositories involved.
>
> And finally we will have CI job to publish final documentation in one
> place. And this job will build and publish every part into separate
> subfolder, so we'll get final docs in one place but built
> independently.
>
>
> https://review.openstack.org/#/c/143679/1/nailgun/docs/api_doc.rst,cm
>
> --
> Aleksandra Fedorova
> Fuel DevOps Engineer
> bookwar