← Back to team overview

fuel-dev team mailing list archive

Re: [Fuel build system] Documentation

 

Hello all,

Of course, I'll do my best to help. I wonder if there is some common
approach allowing to make PDF build work with autodoc. Christopher,
feel free to write me in skype or IRC to discuss this thing.

On Thu, Oct 9, 2014 at 11:43 PM, Dmitry Pyzhov <dpyzhov@xxxxxxxxxxxx> wrote:
> Irina,
>
> thanks a lot. I think deprecated options should not be added to the
> documentation. We should do it in future for changes in documentation. But
> now we should discuss them and simply remove from our build system.
>
> What is more important for our build docs, we should find and document
> general use cases for build system. For example: how to add a package to the
> iso, what to do in case of build failures, how to speed up a build with a
> mirror in local network. Looks like we need a brainstorm here.
>
> Nick, could you help Christopher in investigation of the issue with docs
> movement?
>
> On Thu, Oct 9, 2014 at 12:13 AM, Christopher Aedo <caedo@xxxxxxxxxxxx>
> wrote:
>>
>> Irina, I've had a chance to look through the etherpad and the commit
>> and I think it looks really good.  It's excellent information, looking
>> forward to getting it in our docs!
>>
>> I think this information should be part of the development
>> information.  To that end, it should be part of the "Fuel Development
>> Guide" being added to fuel-docs repo.  The contents of the guide right
>> now consist of all the contents of fuel-web/docs.  This is a
>> work-in-progress, though it's very close to being ready to merge.
>> This commit has no significant content changes to what was pulled from
>> fuel-web/docs, it just organizes them into a new section in fuel-docs
>> called "Fuel Development Guide"
>> https://review.openstack.org/#/c/125234/
>>
>> Right now, the HTML docs build correctly but the PDF docs do not.  It
>> has to do with a path issue, and I could use some help sorting it out.
>> The problem I'm hitting has to do with the path to nailgun being
>> inserted (around line 14 in fuel-docs/common_conf.py).  This is
>> necessary for the automodule component of Sphinx to find and walk
>> through the nailgun code, and build API documentation.
>>
>> If I use sys.path.insert(0,
>> os.path.abspath("_build/repos/fuel-web/nailgun")) then HTML docs work
>> great, API stuff builds as it should, but "make pdf" leads to the API
>> section being empty in the PDF doc Fuel Development Guide.
>>
>> if I use sys.path.insert(0, "_build/repos/fuel-web/nailgun") then
>> again, HTML docs work great, and fuel dev guide PDF is perfect
>> including all API stuff from autodoc - but the other PDF docs all fail
>> due to errors.
>>
>> -Christopher
>>
>>
>>
>>
>> On Wed, Oct 8, 2014 at 12:39 PM, Mike Scherbakov
>> <mscherbakov@xxxxxxxxxxxx> wrote:
>> > Hi Irina,
>> > Crhristopher - can you please join in?
>> >
>> > Description of build system falls into development documentation
>> > category.
>> > It's pity to know that you are experiencing issues with fuel-dev docs
>> > builds. Can you talk more about those?
>> >
>> > I see, for example, patch https://review.openstack.org/#/c/125648/. If
>> > you
>> > go down the page, click Toggle CI, you will see comments from Jenkins.
>> > One
>> > of them is the link
>> >
>> > https://fuel-jenkins.mirantis.com/job/stackforge-verify-fuel-web-docs/4683/.
>> > This link open Jenkins UI, and there you will find
>> > Fuel Development Docs build results [1] on the left - which shows you
>> > how
>> > your documentation would look like after merge.
>> >
>> > [1]
>> >
>> > https://fuel-jenkins.mirantis.com/job/stackforge-verify-fuel-web-docs/4683/Fuel_Development_Docs_build_results
>> >
>> > Thanks,
>> >
>> > On Tue, Oct 7, 2014 at 3:28 PM, Irina Povolotskaya
>> > <ipovolotskaya@xxxxxxxxxxxx> wrote:
>> >>
>> >> Dear colleagues,
>> >>
>> >> According to the bug, I started describing Fuel build system.
>> >> When doing that, I faced some issues:
>> >>
>> >> According to the bug, I should put the doc into fuel-web repo.
>> >> Nevertheless, it's impossible to build documentation there (e.g. to
>> >> check
>> >> formatting via "make pdf/html" command). Thus, the doc was put into
>> >> fuel-docs repo. Currently, it's supposed that all documentation will be
>> >> kept
>> >> in one place; fuel-docs is targeted at end users while fuel-web deals
>> >> with
>> >> development. So, I'd like to understand, where I should put it. For now
>> >> it's
>> >> kept in fuel-docs in Operations Guide. I need to know, what fits best
>> >> in
>> >> this case and I can't help asking your opinion on this problem.
>> >>
>> >> Vladimir Kozhukalov helped me a lot when making up a doc structure and
>> >> describing basic steps to build an iso. Nevertheless, I need more
>> >> feedback
>> >> from those who know about modules structure (repos, mirror, puppet,
>> >> packages, OpenStack packages, Docker, upgrade, Virtual box,
>> >> fuelweb_test)
>> >> and what actually these modules do. I left some questions in the
>> >> commit.
>> >>
>> >> So, I'm kindly asking you to help me to create a clear document on
>> >> build
>> >> structure and available options.
>> >>
>> >> Any feedback is welcome!
>> >>
>> >>
>> >>
>> >> Commit for review is placed here
>> >> https://review.openstack.org/#/c/125928/
>> >>
>> >> Thank you for help!
>> >>
>> >>
>> >> Irina
>> >>
>> >>
>> >> --
>> >> Mailing list: https://launchpad.net/~fuel-dev
>> >> Post to     : fuel-dev@xxxxxxxxxxxxxxxxxxx
>> >> Unsubscribe : https://launchpad.net/~fuel-dev
>> >> More help   : https://help.launchpad.net/ListHelp
>> >>
>> >
>> >
>> >
>> > --
>> > Mike Scherbakov
>> > #mihgen
>> >
>>
>> --
>> Mailing list: https://launchpad.net/~fuel-dev
>> Post to     : fuel-dev@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~fuel-dev
>> More help   : https://help.launchpad.net/ListHelp
>
>



-- 
Best regards,
Nick Markov


References