Merge lp:~rvb/maas/show-version-doc into lp:~maas-committers/maas/trunk

[Raphaël Badin]

Add the bzr last revision, last revision date, and build date to the documentation pages.

We're about to change the docs on maas.ubuntu.com to publish the documentation for multiple versions. It will be very useful to have the bzr revision displayed on the doc pages to detect when the published documentation is outdated. I've added that info into the footer; here is how it looks like: http://people.canonical.com/~rvb/bzr-info.png.

[Gavin Panella (allenap)]

[1]

+bzr_last_revision_number = check_output(['bzr', 'revno'])
+bzr_last_revision_date = check_output(['bzr', 'version-info', '--template={date}','--custom'])
+bzr_build_date = check_output(['bzr', 'version-info', '--template={build_date}','--custom'])

Space after commas.

Strip whitespace from the outputs too?

[2]

It would be good to have the branch name too. Short name (i.e. lp...)
would be best, but I don't know if that's easy to get out of bzr.

review: Approve

[Raphaël Badin (rvb)]

> [1]
>
> +bzr_last_revision_number = check_output(['bzr', 'revno'])
> +bzr_last_revision_date = check_output(['bzr', 'version-info', '--
> template={date}','--custom'])
> +bzr_build_date = check_output(['bzr', 'version-info', '--
> template={build_date}','--custom'])
>
> Space after commas.

Right, done.

> Strip whitespace from the outputs too?

Why? The dates are fine as bzr outputs them I think.

> [2]
>
> It would be good to have the branch name too. Short name (i.e. lp...)
> would be best, but I don't know if that's easy to get out of bzr.

I agree, but I don't know how to get that. More importantly, I'm not sure this information is always available depending on how you created the branch.

[Julian Edwards (julian-edwards)]

On Friday 11 Apr 2014 09:29:20 you wrote:
> +# Gather information about the branch and the build date.
> +from subprocess import check_output
> +bzr_last_revision_number = check_output(['bzr', 'revno'])
> +bzr_last_revision_date = check_output(['bzr', 'version-info',
> '--template={date}','--custom']) +bzr_build_date = check_output(['bzr',
> 'version-info', '--template={build_date}','--custom'])

You know that bzr is written in Python and has an API right? :)

[Julian Edwards (julian-edwards)]

On Friday 11 Apr 2014 09:37:35 you wrote:
> It would be good to have the branch name too. Short name (i.e. lp...)
> would be best, but I don't know if that's easy to get out of bzr.

*cough* bzrlib *cough*

:)

[Raphaël Badin (rvb)]

On 04/11/2014 01:54 PM, Julian Edwards wrote:
> On Friday 11 Apr 2014 09:29:20 you wrote:
>> +# Gather information about the branch and the build date.
>> +from subprocess import check_output
>> +bzr_last_revision_number = check_output(['bzr', 'revno'])
>> +bzr_last_revision_date = check_output(['bzr', 'version-info',
>> '--template={date}','--custom']) +bzr_build_date = check_output(['bzr',
>> 'version-info', '--template={build_date}','--custom'])
>
> You know that bzr is written in Python and has an API right? :)

I know. I deliberately used the command line because:
- I don't want to add yet another dependency (even a dev one) to maas
for such a small thing.
- I tried once to use bzrlib and the doc is absolutely horrible.
Couldn't figure out how to do the simplest operations.
- If someday we move to an other tool to manage the source code (and I
hope we'll do so sooner rather than later) it will be simpler to port
this stuff if we use the command line now.

[Julian Edwards (julian-edwards)]

On Friday 11 Apr 2014 12:03:14 you wrote:
> - If someday we move to an other tool to manage the source code (and I
> hope we'll do so sooner rather than later)

Blasphemy!

=== modified file 'docs/_templates/maas/layout.html'
--- docs/_templates/maas/layout.html	2014-04-08 20:58:05 +0000
+++ docs/_templates/maas/layout.html	2014-04-11 09:43:00 +0000
@@ -14,7 +14,12 @@
 <footer class="global clearfix">
   <div class="legal clearfix">
     <p>&copy; Copyright {{ copyright }}. Ubuntu and Canonical are registered trademarks of
-      <a href="http://canonical.com">Canonical Ltd</a></p>
+      <a href="http://canonical.com">Canonical Ltd</a>.
+    </p>
+    <p>
+      Revision {{ bzr_last_revision_number}} ({{ bzr_last_revision_date }}).
+      Documentation generation date: {{ bzr_build_date }}.
+    </p>
   </div>
 </footer>
 {%- endblock %}

=== modified file 'docs/conf.py'
--- docs/conf.py	2014-04-08 20:58:05 +0000
+++ docs/conf.py	2014-04-11 09:43:00 +0000
@@ -279,9 +279,18 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
 
+# Gather information about the branch and the build date.
+from subprocess import check_output
+bzr_last_revision_number = check_output(['bzr', 'revno'])
+bzr_last_revision_date = check_output(['bzr', 'version-info', '--template={date}', '--custom'])
+bzr_build_date = check_output(['bzr', 'version-info', '--template={build_date}', '--custom'])
+
 # Populate html_context with the variables used in the templates.
 html_context = {
     'add_version_switcher': 'true' if add_version_switcher else 'false',
     'versions_json_path': '/'.join(['', doc_prefix, versions_path]),
     'doc_prefix': doc_prefix,
+    'bzr_last_revision_date': bzr_last_revision_date,
+    'bzr_last_revision_number': bzr_last_revision_number,
+    'bzr_build_date': bzr_build_date,
 }