[openstack-dev] [Fuel][Docs] Move fuel-web/docs to fuel-docs

Christopher Aedo caedo at mirantis.com
Wed Dec 24 22:32:20 UTC 2014


I think it's worth pursuing these efforts to include the
auto-generated doc components in the fuel-docs build process.  The
additional dependencies required to build nailgun are not so
unreasonable, and the preparation of the build environment has already
been put into a single script,

>From the CI perspective, where do the CI slaves "start" so to speak?
I do not think we are starting from a bare machine, installing OS,
installing dependencies, and then attempting a build of fuel-docs
right?  I'm wondering here whether it's reasonable to start from a
snapshot where the machine has the necessary dependencies (it must
start from some snapshotted point, otherwise just testing change of a
single line would take unreasonably long).

>From your steps:
> 6) Implement additional make target in fuel-docs
> to download and build autodocs from fuel-web
> repo as a separate chapter.

If we add this as an additional make target, then the environment
would have to support the necessary dependencies anyway, right?  If
that's the case, then this would have to be testable no matter what,
right?  Or is it suggested that this step would not be tested, and
would essentially stand off on it's own?

-Christopher

On Tue, Dec 23, 2014 at 9:20 AM, Aleksandra Fedorova
<afedorova at mirantis.com> wrote:
> 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



More information about the OpenStack-dev mailing list