Open Stack

Hi Bernd! Great questions.

On Thu, Feb 26, 2015 at 3:06 AM, Bernd Bausch <berndbausch at gmail.com> wrote:

> First, I hope it’s OK if a newbie uses this mailing list to request help
> for bug fixing. If there are better ways, please let me know.
>

Absolutely use this list!


>
>
> The bug in question is
> https://bugs.launchpad.net/openstack-manuals/+bug/1421799. It’s a request
> to add a “log a bug” link to the openstackdocstheme templates, similar to
> the cute red bug links at the top and bottom of each page in the current
> DocBook-based documentation.
>
>
>
> I recklessly assigned this bug to myself. While I should be able to put
> the mechanism in place, I don’t have enough information to construct the
> link into launchpad and could do with some help from knowledgeable people.
>

Hehe on recklessly. :)


>
>
> In the current documentation, the bug link is a launchpad URL that
> contains the book title (such as “SLES 11 installation guide”) and
> information of the following form:
>
>
>
> -----------------------------------
> Built: 2015-02-17T17:45:22 00:00
> git SHA: 3f5dd2abd6d6f94cfffcb26f88c830da38af5d9e
> URL:
> http://docs.openstack.org/juno/config-reference/content/section_compute-scheduler.html
> source File:
> file:/home/jenkins/workspace/openstack-manuals-tox-doc-publishdocs/doc/config-reference/compute/section_compute-scheduler.xml
> xml:id: section_compute-scheduler
>
>
>
> My question is: Where would I find equivalent information in the
> Sphinx/Jinja environment?
>
> The Sphinx documentation lists a few promising helper functions and
> variables (http://sphinx-doc.org/templating.html#helper-functions). It
> seems that some settings are derived from conf.py, and I don’t know if
> there is any conf.py standard that I can base this on.
>
> No idea how to retrieve the SHA key, and what to use instead of the XML ID
> (or can it just be left out).
>

Those helper-functions don't have what we need, but they can be a model to
make what we need, and then inserted into our theme, openstackdocstheme.

Tom's got the basic idea of what we need, and the next step is to figure
out how to create our own helper function for our launchpad bug link
creation. I might be totally wrong here, but think we'll need an HTML
template like what Read the Docs does to make their breadcrumbs:

https://github.com/snide/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/breadcrumbs.html

What I'd have to look at with you, and I'm happy to do so, is where to put
this in our theme. Probably in the html templates. Then next figure out how
to make that html template be output in the place where the little bug icon
goes on every page.


>
>
> Rather than asking for help, I could also just implement whatever I can
> and leave a few gaps for more experienced people or reviewers. Is that an
> acceptable approach?
>

I'd be happy to collaborate with you on a patch, then you can also get used
to the gerrit/git review ways of patching patches. So feel free to upload
anything, even if you just want to practice patching, and then reach out to
me on the list so I can take a look. Should be fun!
Anne


>
>
> Regards,
>
>
>
> Bernd
>
> Bernd Bausch
>
> berndbausch at gmail.com
>
> +81 80 8892 5564
>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150227/1f909749/attachment-0001.html>