[openstack-dev] [telemetry] Ceilometer and Aodh install guide(s)
Hi, I'm currently working on to move the Install Guide for Ceilometer [1] and Aodh [2] under the project trees. I faced with a few difficulties so far about which I would like to ask your opinion. First of all these two projects are under the Telemetry umbrella, so they are not completely separate. I tried to name the services in the documents accordingly in the files. My question here would be whether these two guides will be included in the overall document as two totally standalone services or we can link them together somehow? The other question I had in mind is in connection with removing ".. only::". As Ceilometer is integrated with several other projects it needs additional configuration steps, where we have distro specific steps to follow. I chose the direction of extracting the common parts and reused them in the distro specific files. The end result still looks ugly and I have concerns about maintainability. We merged a first version of the structure, but I'm happy to change if we can come up with a better solution. Do you have suggestions on this? I have a third less urgent question. The install-guide has it's own folder at the same level where these two projects have their 'doc' folder. I would assume other projects have the same or similar folder for the developer docs. Would that be reasonable/possible to have one main 'doc' folder for all the docs? Thanks and Best Regards, Ildikó [1] https://review.openstack.org/#/c/330051/ [2] https://review.openstack.org/#/c/330048/ __ 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] [telemetry] Ceilometer and Aodh install guide(s)
> -Original Message- > From: Ildikó Váncsa [mailto:ildiko.van...@ericsson.com] > Sent: Tuesday, June 28, 2016 7:56 AM > To: openstack-d...@lists.openstack.org > Cc: openstack-dev@lists.openstack.org > Subject: [OpenStack-docs] [telemetry] Ceilometer and Aodh install > guide(s) snip > > The other question I had in mind is in connection with removing ".. > only::". As Ceilometer is integrated with several other projects it needs > additional configuration steps, where we have distro specific steps to > follow. I chose the direction of extracting the common parts and reused > them in the distro specific files. The end result still looks ugly and I have > concerns about maintainability. We merged a first version of the > structure, but I'm happy to change if we can come up with a better > solution. Do you have suggestions on this? > [] I would suggest a modular approach with the use of .. include:: It would look something like this: == Instructions for Ubuntu == .. include:: file-with-common-steps.rst .. include:: file-with-ubuntu-steps.rst Then you can do the same for each distro. Having all the separate procedures in different files should help solve your maintainability concerns. Regards, Rodrigo Caballero snip > > Thanks and Best Regards, > Ildikó > > [1] https://review.openstack.org/#/c/330051/ > [2] https://review.openstack.org/#/c/330048/ > > ___ > OpenStack-docs mailing list > openstack-d...@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs __ 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] [telemetry] Ceilometer and Aodh install guide(s)
On Tue, Jun 28 2016, Ildikó Váncsa wrote: > I have a third less urgent question. The install-guide has it's own folder at > the same level where these two projects have their 'doc' folder. I would > assume > other projects have the same or similar folder for the developer docs. Would > that be reasonable/possible to have one main 'doc' folder for all the docs? This is our long-term objective for Telemetry projects. Gnocchi already have only one doc/ folder with all the documentation, From installation to usage. I don't think our projects are not big enough and have enough resources to start maintaining different documentations with different scopes, etc. -- Julien Danjou ;; Free Software hacker ;; https://julien.danjou.info signature.asc Description: PGP signature __ 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] [telemetry] Ceilometer and Aodh install guide(s)
+1 on the modular approach by Rodrigo Caballero I'm writing magnum's guide and I'm working on the debian guide. Debian's guide will have a couple of differences and I plan to move them in other files or/and break the existing common config files. IMO, one of the goals of the project specific guides was to let teams decide what works for them. If the output guide is similar to others, I think you can choose what suits you best. Cheers, Spyros On 28 June 2016 at 16:44, Julien Danjou wrote: > On Tue, Jun 28 2016, Ildikó Váncsa wrote: > > > I have a third less urgent question. The install-guide has it's own > folder at > > the same level where these two projects have their 'doc' folder. I would > assume > > other projects have the same or similar folder for the developer docs. > Would > > that be reasonable/possible to have one main 'doc' folder for all the > docs? > > This is our long-term objective for Telemetry projects. > > Gnocchi already have only one doc/ folder with all the documentation, > From installation to usage. > > I don't think our projects are not big enough and have enough resources > to start maintaining different documentations with different scopes, > etc. > > -- > Julien Danjou > ;; Free Software hacker > ;; https://julien.danjou.info > > __ > 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 > > __ 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] [telemetry] Ceilometer and Aodh install guide(s)
Hi, @Julien: +1 to the one 'doc' folder. I think it's not yet decided whether it should be modular, using '.. only::' or we can/will have both. I use the modular approach as well right now, I have many files containing the common things and the distro specific steps. For Ceilometer it resulted in way more files and folders than it should be in my opinion. And I think it will discourage people from contributing to it. The more files you have the harder to see how the guide will look like after the build, which can make it slower to identify and then modify the files. Do you have a good proposal for structuring things? Thanks, /Ildikó > -Original Message- > From: Spyros Trigazis [mailto:strig...@gmail.com] > Sent: June 28, 2016 17:18 > To: OpenStack Development Mailing List (not for usage questions); Ildikó > Váncsa; openstack-d...@lists.openstack.org > Subject: Re: [openstack-dev] [telemetry] Ceilometer and Aodh install guide(s) > > +1 on the modular approach by Rodrigo Caballero > > I'm writing magnum's guide and I'm working on the debian guide. Debian's > guide will have a couple of differences and I plan to move > them in other files or/and break the existing common config files. > > IMO, one of the goals of the project specific guides was to let teams decide > what works for them. If the output guide is similar to > others, I think you can choose what suits you best. > > Cheers, > Spyros > > > On 28 June 2016 at 16:44, Julien Danjou wrote: > > > On Tue, Jun 28 2016, Ildikó Váncsa wrote: > > > I have a third less urgent question. The install-guide has it's own > folder at > > the same level where these two projects have their 'doc' folder. I > would assume > > other projects have the same or similar folder for the developer > docs. Would > > that be reasonable/possible to have one main 'doc' folder for all the > docs? > > This is our long-term objective for Telemetry projects. > > Gnocchi already have only one doc/ folder with all the documentation, > From installation to usage. > > I don't think our projects are not big enough and have enough resources > to start maintaining different documentations with different scopes, > etc. > > -- > Julien Danjou > ;; Free Software hacker > ;; https://julien.danjou.info > > > __ > 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 > > > __ 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