Merge lp:~chris.gagnon/autopilot/added-contribute-documentation into lp:autopilot

[Chris Gagnon]

add how to contribute documentation

[lp:~chris.gagnon/autopilot/added-contribute-documentation]

243. By Chris Gagnon on 2013-06-11

remove duplicate word in faq

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:243
http://jenkins.qa.ubuntu.com/job/autopilot-ci/125/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/53
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/53

Click here to trigger a rebuild:
http://s-jenkins:8080/job/autopilot-ci/125/rebuild

review: Approve (continuous-integration)

[lp:~chris.gagnon/autopilot/added-contribute-documentation]

244. By Chris Gagnon on 2013-06-11

remove unused css from layout.html in docs

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:244
http://jenkins.qa.ubuntu.com/job/autopilot-ci/126/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/54
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/54

Click here to trigger a rebuild:
http://s-jenkins:8080/job/autopilot-ci/126/rebuild

review: Approve (continuous-integration)

[Francis Ginther (fginther)]

The 'Learn how you can contribute!" line at the top and bottom look out of place to me. I'd like to see it integrated better, maybe add it here: "modules | index | Contribute!"? I've asked the bug reported to clarify with an example.

Also, in the even this link gets added, the '#' should be removed in:
7 + <a href="{{pathto("faq/faq")}}#q-how-can-i-contribute-to-autopilot"> Learn how you can contribute!</a><br/>
11 + <a href="{{pathto("faq/faq")}}#q-how-can-i-contribute-to-autopilot"> Learn how you can contribute!</a><br/>

the link currently expands to:
.../faq.html##q-how-can-i-contribute-to-autopilot

review: Needs Information

[Chris Gagnon (chris.gagnon)]

I just saw the ## in the url, the double #'s only happen when clicking that link from the faq page, it works from other pages. I'll have to figure out how to fix that.

[Francis Ginther (fginther)]

The python docs (http://docs.python.org/2/tutorial/index.html) have this in the footer, where "Found a bug?" is a link:

© Copyright 1990-2013, Python Software Foundation.
The Python Software Foundation is a non-profit corporation. Please donate.
Last updated on Jun 11, 2013. Found a bug?
Created using Sphinx 1.0.7.

I would be in favor of something similar to this format for the how to contribute link.

[Chris Gagnon (chris.gagnon)]

I can center the header and footer and have the color match so it blends seamlessly.

It's harder than I thought to make sure the link to the anchor doesn't double the # on the faq. because .html is also automatically appended to the link.

I think I need to make a separate contribute page.

[lp:~chris.gagnon/autopilot/added-contribute-documentation]

245. By Chris Gagnon on 2013-06-13

add css file to center text and color header and footer

[Chris Gagnon (chris.gagnon)]

I moved the contribute section to the top of the FAQ page

review: Needs Resubmitting

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:245
http://jenkins.qa.ubuntu.com/job/autopilot-ci/130/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/58
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/58

Click here to trigger a rebuild:
http://s-jenkins:8080/job/autopilot-ci/130/rebuild

review: Approve (continuous-integration)

[Francis Ginther (fginther)]

When I build the docs from trunk, I get a copyright message in the footer:
© Copyright 2012-2013, Canonical. Created using Sphinx 1.1.3.

This is not being generated with this MP.

Also, the new header should be removed. Having the contribute link in the footer is sufficient.

The content looks good. I'll re-review when the contribute page is ready.

[lp:~chris.gagnon/autopilot/added-contribute-documentation]

246. By Chris Gagnon on 2013-06-14

add new contribute file and fix up links

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:246
http://jenkins.qa.ubuntu.com/job/autopilot-ci/131/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/59
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/59

Click here to trigger a rebuild:
http://s-jenkins:8080/job/autopilot-ci/131/rebuild

review: Approve (continuous-integration)

[lp:~chris.gagnon/autopilot/added-contribute-documentation]

247. By Chris Gagnon on 2013-06-14

add new table row for additional item in index.html

248. By Chris Gagnon on 2013-06-14

add file a bug link to footer in documentation

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:248
http://jenkins.qa.ubuntu.com/job/autopilot-ci/132/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/60
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/60

Click here to trigger a rebuild:
http://s-jenkins:8080/job/autopilot-ci/132/rebuild

review: Approve (continuous-integration)

[lp:~chris.gagnon/autopilot/added-contribute-documentation]

249. By Chris Gagnon on 2013-06-14

add section for listing tests

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:249
http://jenkins.qa.ubuntu.com/job/autopilot-ci/133/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/61
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/61

Click here to trigger a rebuild:
http://s-jenkins:8080/job/autopilot-ci/133/rebuild

review: Approve (continuous-integration)

[Francis Ginther (fginther)]

The contribute page looks very good, I just found a few proofreading corrections:

82 +* Test and Fix: No project is perfect, log some `bugs <https://bugs.launch pad.net/autopilot/+filebug>`_ or `fix some bugs <https://bugs.launchpad.net/autopilot/+filebug>`_.

There are extra spaces in the report a bug link. The second link should just go to the bug list: <https://bugs.launchpad.net/autopilot>

119 +All new features should have unit and/or functional test to make sure someone doesn't remove break your new code with a future commit.

Should that be "remove or break"?

123 +From the directory containing the autopilot source code and list the tests::

Sounds like it's missing something. Maybe "From the directory containing the autopilot source code, you can list the tests"?

The footer has been a lot more complicated then I expected. The original footer is generated by a parameterized sphinx layout.html file (the copyright dates, etc. come from the conf.py file or sphinx itself). We should continue to use the parameters so that the layout.html doesn't need to be changed when those parameters change. For the life of me, I can't figure out from the sphinx docs if there is a way to 'subclass' the original footer and just add the contribute and bug links. So...

The best I could come up with is just a copy and paste of the footer block from /usr/share/sphinx/themes/basic/layout.html:

docs/_templates/layout.html:
{% extends '!layout.html' %}
{% set css_files = css_files + ["_static/centertext.css"] %}

{% block footer %}
    <div class="footer">
      <div class=center_text>
        <a href="{{pathto("faq/contribute") }}">Learn how you can contribute!</a> / <a href="https://bugs.launchpad.net/autopilot/+filebug">File a bug</a>
     <br/>
      </div>
    {%- if show_copyright %}
      {%- if hasdoc('copyright') %}
        {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
      {%- else %}
        {% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.{% endtrans %}
      {%- endif %}
    {%- endif %}
    {%- if last_updated %}
      {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
    {%- endif %}
    {%- if show_sphinx %}
      {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
    {%- endif %}
    </div>

{% endblock %}

Once I did this, I had to remove the background color from div.center_text as the footer class had a slightly different color.

Maybe there is a better way to do this, I'm not very familiar with these templating tools.

Also, I really like the "You know you want to."

review: Needs Fixing

[lp:~chris.gagnon/autopilot/added-contribute-documentation]

250. By Chris Gagnon on 2013-06-14

fix footer and links in contribute page

[Chris Gagnon (chris.gagnon)]

I fixed the links

add or between break and remove

I broke apart the list and run so they are separate questions

and used your layout file for the footer.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:250
http://jenkins.qa.ubuntu.com/job/autopilot-ci/134/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/62
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/62

Click here to trigger a rebuild:
http://s-jenkins:8080/job/autopilot-ci/134/rebuild

review: Approve (continuous-integration)

[lp:~chris.gagnon/autopilot/added-contribute-documentation]

251. By Chris Gagnon on 2013-06-14

remove extra word from contribute.rst

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:251
http://jenkins.qa.ubuntu.com/job/autopilot-ci/135/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-amd64-ci/63
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-saucy-armhf-ci/63

Click here to trigger a rebuild:
http://s-jenkins:8080/job/autopilot-ci/135/rebuild

review: Approve (continuous-integration)

[Francis Ginther (fginther)]

Sweetbix.

review: Approve

=== added file 'docs/_static/centertext.css'
--- docs/_static/centertext.css	1970-01-01 00:00:00 +0000
+++ docs/_static/centertext.css	2013-06-14 16:31:37 +0000
@@ -0,0 +1,9 @@
+div.center_text {
+    text-align: center;
+    color: #ffffff;
+}
+
+div.center_text a {
+    color: #ffffff;
+}
+

=== modified file 'docs/_templates/indexcontent.html'
--- docs/_templates/indexcontent.html	2013-04-16 22:51:59 +0000
+++ docs/_templates/indexcontent.html	2013-06-14 16:31:37 +0000
@@ -26,6 +26,14 @@
       </td>
       <td>
         <p class="biglink">
+          <a class="biglink" href="{{ pathto("faq/contribute") }}">How to contribute to autopilot</a><br/>
+          <span class="linkdescr">You know you want to.</span>
+          </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class="biglink">
           <a class="biglink" href="{{ pathto("porting/porting") }}">Porting Autopilot Tests</a><br/>
           <span class="linkdescr">How to port your tests from earlier versions of Autopilot.</span>
         </p>

=== added file 'docs/_templates/layout.html'
--- docs/_templates/layout.html	1970-01-01 00:00:00 +0000
+++ docs/_templates/layout.html	2013-06-14 16:31:37 +0000
@@ -0,0 +1,25 @@
+{% extends '!layout.html' %}
+{% set css_files = css_files + ["_static/centertext.css"] %}
+
+{% block footer %}
+    <div class="footer">
+      <div class=center_text>
+        <a href="{{pathto("faq/contribute") }}">Learn how you can contribute!</a> / <a href="https://bugs.launchpad.net/autopilot/+filebug">File a bug</a>
+     <br/>
+      </div>
+    {%- if show_copyright %}
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
+      {%- else %}
+        {% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.{% endtrans %}
+      {%- endif %}
+    {%- endif %}
+    {%- if last_updated %}
+      {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
+    {%- endif %}
+    {%- if show_sphinx %}
+      {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
+    {%- endif %}
+    </div>
+
+{% endblock %}

=== modified file 'docs/contents.rst'
--- docs/contents.rst	2013-04-16 21:24:39 +0000
+++ docs/contents.rst	2013-06-14 16:31:37 +0000
@@ -10,3 +10,4 @@
     api/index
     porting/porting
     faq/faq
+    faq/contribute

=== added file 'docs/faq/contribute.rst'
--- docs/faq/contribute.rst	1970-01-01 00:00:00 +0000
+++ docs/faq/contribute.rst	2013-06-14 16:31:37 +0000
@@ -0,0 +1,70 @@
+Contribute
+##########################
+
+.. contents::
+
+Autopilot: Contributing
++++++++++++++++++++++++
+Q. How can I contribute to autopilot?
+=====================================
+* Documentation: We can always use more documentation.
+    * if you don't know how to submit a merge proposal on launchpad, you can write a `bug <https://bugs.launchpad.net/autopilot/+filebug>`_ with new documentation and someone will submit a merge proposal for you. They will give you credit for your documentation in the merge proposal.
+
+
+* New Features: Check out our existing `Blueprints <https://blueprints.launchpad.net/autopilot>`_ or create some yourself... Then code!
+
+
+* Test and Fix: No project is perfect, log some `bugs <https://bugs.launchpad.net/autopilot/+filebug>`_ or `fix some bugs <https://bugs.launchpad.net/autopilot>`_.
+
+Q. Where can I get help / support?
+==================================
+
+The developers hang out in the #ubuntu-autopilot IRC channel on irc.freenode.net.
+
+Q. How do I download the code?
+==============================
+Autopilot is using Launchpad and Bazaar for source code hosting. If you're new to Bazaar, or distributed version control in general, take a look at the `Bazaar mini-tutorial first. <http://doc.bazaar.canonical.com/bzr.dev/en/mini-tutorial/index.html>`_
+
+Install bzr open a terminal and type::
+
+    sudo apt-get install bzr
+
+Download the code::
+
+    bzr branch lp:autopilot
+
+This will create an autopilot directory and place the latest code there. You can also view the autopilot code `on the web <https://launchpad.net/autopilot>`_
+
+
+Q. How do I submit the code for a merge proposal?
+=================================================
+After making the desired changes to the code or documentation and making sure the tests still run type::
+
+    bzr commit
+
+Write a quick one line description of the bug that was fix or the documentation that was written.
+
+Signup for a `launchpad account <https://help.launchpad.net/YourAccount/NewAccount>`_, if you don't have one. Then using your launchpad id type::
+
+    bzr push lp:~<launchpad-id>/autopilot/<text about merge here>
+
+    example:
+    bzr push lp:~chris.gagnon/autopilot/bug-fix-lp234567
+
+All new features should have unit and/or functional test to make sure someone doesn't remove or break your new code with a future commit.
+
+Q. How do I list the tests for the autopilot source code?
+=========================================================
+From the directory containing the autopilot source code type::
+
+    autopilot list autopilot.tests
+
+Q. How do I run the tests for the autopilot source code?
+========================================================
+From the directory containing the autopilot source code type::
+
+    autopilot run autopilot.tests
+
+To run a single test::
+
+    autopilot run autopilot.tests.unit.test_version_utility_fns.VersionFnTests.test_get_version_string_shows_source_version

=== modified file 'docs/faq/faq.rst'
--- docs/faq/faq.rst	2013-05-01 00:48:34 +0000
+++ docs/faq/faq.rst	2013-06-14 16:31:37 +0000
@@ -5,6 +5,10 @@
 
 Autopilot: The Project
 ++++++++++++++++++++++
+Q. Where can I get help / support?
+==================================
+
+The developers hang out in the #ubuntu-autopilot IRC channel on irc.freenode.net.
 
 Q. How do I install Autopilot?
 ==============================
@@ -20,11 +24,6 @@
 
 Autopilot is hosted on launchpad - bugs can be reported on the `launchpad bug page for autopilot <https://bugs.launchpad.net/autopilot/+filebug>`_ (this requires a launchpad account).
 
-Q. Where can I get help / support?
-==================================
-
-The developers hang out in the #ubuntu-quality IRC channel on irc.freenode.net.
-
 Q. What type of applications can autopilot test?
 ================================================