Open Stack

Anne,

 

a first attempt at a partial fix is now in the system https://review.openstack.org/#/c/160151/. Regarding the readthedocs breadcrumb implementation, the question is: Where does information like this come from:

 

{{ github_user }}/{{ github_repo }}/blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ source_suffix }}

 

Is there a process that, for example, populates conf.py with github_user and so on? For a meaningful bug report in our context, it would have to be information like name of the source file, URL of the finished HTML etc.

 

If anybody else on the distribution list has an idea, don’t hold back!

 

Bernd Bausch

 <mailto:berndbausch at gmail.com> berndbausch at gmail.com

+81 80 8892 5564

 

From: Anne Gentle [mailto:annegentle at justwriteclick.com] 
Sent: 2015年2月28日 0:51
To: Bernd Bausch
Cc: openstack-docs at lists.openstack.org
Subject: Re: [OpenStack-docs] Adding "Log a doc bug" link to openstackdocstheme

 

Hi Bernd! Great questions.

 

On Thu, Feb 26, 2015 at 3:06 AM, Bernd Bausch <berndbausch at gmail.com <mailto: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 <mailto:berndbausch at gmail.com> 

+81 80 8892 5564 <tel:%2B81%2080%208892%205564> 

 


_______________________________________________
OpenStack-docs mailing list
OpenStack-docs at lists.openstack.org <mailto:OpenStack-docs at lists.openstack.org> 
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs





 

-- 

Anne Gentle
annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150301/013c6a51/attachment.html>