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

2015-01-14 Thread Christopher Aedo
Adjusting fuel-web/docs to build ONLY the API and Objects reference is here:
https://review.openstack.org/147348

Meg should have the inclusion of fuel-web/docs content in fuel-docs tomorrow.

Once these two are done, we can sort out that last step:
 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.

-Christopher

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


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

2014-12-25 Thread Aleksandra Fedorova
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

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


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

2014-12-25 Thread Christopher Aedo
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
afedor...@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

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


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

2014-12-24 Thread Christopher Aedo
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
afedor...@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

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


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

2014-12-23 Thread Aleksandra Fedorova
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

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev