Open Stack

Blueprint https://blueprints.launchpad.net/fuel/+spec/fuel-dev-docs-merge-fuel-docs
suggests us to move all documentation from fuel-web to fuel-docs
repository.

While I agree that moving Developer Guide to fuel-docs is a good idea,
there is an issue with autodocs which currently blocks the whole
process.

If we move dev docs to fuel-docs as suggested by Christopher in [1] we
will make it impossible to build fuel-docs without cloning fuel-web
repository and installing all nailgun dependencies into current
environment. And this is bad from both CI and user point of view.

I think we should keep fuel-docs repository self-contained, i.e. one
should be able to build docs without any external code. We can add a
switch or separate make target to build 'addons' to this documentation
when explicitly requested, but it shouldn't be default behaviour.

Thus I think we need to split documentation in fuel-web/ repository
and move the "static" part to fuel-docs, but keep "dynamic"
auto-generated part in fuel-web repo. See patch [2].

Then to move docs from fuel-web to fuel-docs we need to perform following steps:

1) Merge/abandon all docs-related patches to fuel-web, see full list [3]
2) Merge updated patch [2] which removes docs from fuel-web repo,
leaving autogenerated api docs only.
3) Disable docs CI for fuel-web
4) Add building of api docs to fuel-web/run_tests.sh.
5) Update fuel-docs repository with new data as in patch [4] but
excluding anything related to autodocs.
6) Implement additional make target in fuel-docs to download and build
autodocs from fuel-web repo as a separate chapter.
7) Add this make target in fuel-docs CI.


[1] https://review.openstack.org/#/c/124551/
[2] https://review.openstack.org/#/c/143679/
[3] https://review.openstack.org/#/q/project:stackforge/fuel-web+status:open+file:%255Edoc.*,n,z
[4] https://review.openstack.org/#/c/125234/

-- 
Aleksandra Fedorova
Fuel Devops Engineer
bookwar