Open Stack

On Sun, Mar 1, 2015 at 3:12 AM, Bernd Bausch <berndbausch at gmail.com> wrote:

> 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.
>

Yes, for RTD theme they set it as a variable in conf.py.

http://sphinxjpthemesbasicstrap.readthedocs.org/en/latest/options.html

I'll take a look later today, thanks!
Anne


>
>
> If anybody else on the distribution list has an idea, don’t hold back!
>
>
>
> Bernd Bausch
>
> 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>
> 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
>



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