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 <[email protected]> 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 > <[email protected]> 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 : [email protected] >> 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 : [email protected] Unsubscribe : https://launchpad.net/~fuel-dev More help : https://help.launchpad.net/ListHelp
