suggests us to move all documentation from fuel-web to fuel-docs

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

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/
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.


Aleksandra Fedorova
Fuel Devops Engineer

OpenStack-dev mailing list

Reply via email to