fuel-dev team mailing list archive

[Christopher Aedo <caedo@xxxxxxxxxxxx>]

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
>