Open Stack

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