Skip to content
Snippets Groups Projects
Commit 30060b3c authored by Bienchen's avatar Bienchen
Browse files

Updated documentation

parent b67b99c2
No related branches found
No related tags found
No related merge requests found
Showing
with 237 additions and 108 deletions
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
...@@ -85,7 +85,7 @@ ...@@ -85,7 +85,7 @@
</div> </div>
<div class="footer"> <div class="footer">
&copy; Copyright 2013, Bienchen. &copy; Copyright 2013, Bienchen.
Last updated on May 26 14:31, 2014. Last updated on Jun 14 19:22, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
</div> </div>
</body> </body>
......
...@@ -69,7 +69,7 @@ ...@@ -69,7 +69,7 @@
<span class="sd"> missing.</span> <span class="sd"> missing.</span>
<span class="sd"> &#39;&#39;&#39;</span> <span class="sd"> &#39;&#39;&#39;</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="nb">file</span><span class="p">):</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="nb">file</span><span class="p">):</span>
<span class="k">print</span> <span class="s">&#39;</span><span class="si">%s</span><span class="s"> file does not exist: </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="nb">file</span><span class="p">)</span> <span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;</span><span class="si">%s</span><span class="s"> file does not exist: </span><span class="si">%s</span><span class="se">\n</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="nb">file</span><span class="p">))</span>
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">exit_status</span><span class="p">)</span> <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">exit_status</span><span class="p">)</span>
</div> </div>
<div class="viewcode-block" id="FileExtension"><a class="viewcode-back" href="../../../core/argcheck.html#promod3.core.argcheck.FileExtension">[docs]</a><span class="k">def</span> <span class="nf">FileExtension</span><span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="n">exit_status</span><span class="p">,</span> <span class="nb">file</span><span class="p">,</span> <span class="n">extensions</span><span class="p">,</span> <span class="n">gz</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span> <div class="viewcode-block" id="FileExtension"><a class="viewcode-back" href="../../../core/argcheck.html#promod3.core.argcheck.FileExtension">[docs]</a><span class="k">def</span> <span class="nf">FileExtension</span><span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="n">exit_status</span><span class="p">,</span> <span class="nb">file</span><span class="p">,</span> <span class="n">extensions</span><span class="p">,</span> <span class="n">gz</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span>
...@@ -113,10 +113,10 @@ ...@@ -113,10 +113,10 @@
<span class="n">is_gz</span> <span class="o">=</span> <span class="bp">True</span> <span class="n">is_gz</span> <span class="o">=</span> <span class="bp">True</span>
<span class="n">filename</span><span class="p">,</span> <span class="n">fileext</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span> <span class="n">filename</span><span class="p">,</span> <span class="n">fileext</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">splitext</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">gz</span><span class="p">:</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">gz</span><span class="p">:</span>
<span class="k">print</span> <span class="s">&#39;</span><span class="si">%s</span><span class="s"> file extension not supported: </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="nb">file</span><span class="p">)</span> <span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;</span><span class="si">%s</span><span class="s"> file extension not supported: </span><span class="si">%s</span><span class="se">\n</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="nb">file</span><span class="p">))</span>
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">exit_status</span><span class="p">)</span> <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">exit_status</span><span class="p">)</span>
<span class="k">if</span> <span class="n">fileext</span> <span class="o">==</span> <span class="s">&#39;&#39;</span><span class="p">:</span> <span class="k">if</span> <span class="n">fileext</span> <span class="o">==</span> <span class="s">&#39;&#39;</span><span class="p">:</span>
<span class="k">print</span> <span class="s">&#39;</span><span class="si">%s</span><span class="s"> file extension not supported: </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="nb">file</span><span class="p">)</span> <span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;</span><span class="si">%s</span><span class="s"> file extension not supported: </span><span class="si">%s</span><span class="se">\n</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="nb">file</span><span class="p">))</span>
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">exit_status</span><span class="p">)</span> <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">exit_status</span><span class="p">)</span>
<span class="n">fileext</span> <span class="o">=</span> <span class="n">fileext</span><span class="p">[</span><span class="mi">1</span><span class="p">:]</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="n">fileext</span> <span class="o">=</span> <span class="n">fileext</span><span class="p">[</span><span class="mi">1</span><span class="p">:]</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
<span class="k">for</span> <span class="n">ext</span> <span class="ow">in</span> <span class="n">extensions</span><span class="p">:</span> <span class="k">for</span> <span class="n">ext</span> <span class="ow">in</span> <span class="n">extensions</span><span class="p">:</span>
...@@ -125,7 +125,7 @@ ...@@ -125,7 +125,7 @@
<span class="k">return</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">filename</span><span class="p">),</span> <span class="n">fileext</span><span class="p">,</span> <span class="n">is_gz</span> <span class="k">return</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">filename</span><span class="p">),</span> <span class="n">fileext</span><span class="p">,</span> <span class="n">is_gz</span>
<span class="k">else</span><span class="p">:</span> <span class="k">else</span><span class="p">:</span>
<span class="k">return</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">filename</span><span class="p">),</span> <span class="n">fileext</span> <span class="k">return</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">filename</span><span class="p">),</span> <span class="n">fileext</span>
<span class="k">print</span> <span class="s">&#39;</span><span class="si">%s</span><span class="s"> file extension not supported: </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="nb">file</span><span class="p">)</span> <span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;</span><span class="si">%s</span><span class="s"> file extension not supported: </span><span class="si">%s</span><span class="se">\n</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="nb">file</span><span class="p">))</span>
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">exit_status</span><span class="p">)</span> <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="n">exit_status</span><span class="p">)</span>
</div> </div>
<span class="n">__all__</span> <span class="o">=</span> <span class="p">(</span> <span class="n">__all__</span> <span class="o">=</span> <span class="p">(</span>
...@@ -133,7 +133,8 @@ ...@@ -133,7 +133,8 @@
<span class="s">&#39;FileExtension&#39;</span><span class="p">,</span> <span class="s">&#39;FileExtension&#39;</span><span class="p">,</span>
<span class="p">)</span> <span class="p">)</span>
<span class="c"># LocalWords: gz pdb gzip bool</span> <span class="c"># LocalWords: gz pdb gzip bool os sys FileExists FileExtension filename</span>
<span class="c"># LocalWords: fileext</span>
</pre></div> </pre></div>
</div> </div>
...@@ -173,7 +174,7 @@ ...@@ -173,7 +174,7 @@
</div> </div>
<div class="footer"> <div class="footer">
&copy; Copyright 2013, Bienchen. &copy; Copyright 2013, Bienchen.
Last updated on May 26 14:31, 2014. Last updated on Jun 14 19:22, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
</div> </div>
</body> </body>
......
...@@ -36,9 +36,9 @@ put a ``-D`` in front of options. ...@@ -36,9 +36,9 @@ put a ``-D`` in front of options.
Here is a list of more options used within |project|: Here is a list of more options used within |project|:
* ``DISABLE_DOCUMENTATION`` Don't build documentation, don't search for |sphinx| * ``DISABLE_DOCUMENTATION`` Don't build documentation, don't search for |sphinx|
* ``DISABLE_DOCTEST`` Don't run example code from documentation on 'make check' * ``DISABLE_DOCTEST`` Don't run example code from documentation on
(implicit by ``DISABLE_DOCUMENTATION``) ``make check`` (implicit by ``DISABLE_DOCUMENTATION``)
* ``DISABLE_LINKCHECK`` Don't test links from documentation on 'make check * ``DISABLE_LINKCHECK`` Don't test links from documentation on ``make check``
(implicit by ``DISABLE_DOCUMENTATION``) (implicit by ``DISABLE_DOCUMENTATION``)
Instead of calling |cmake| by yourself, there is the :file:`conf-scripts` Instead of calling |cmake| by yourself, there is the :file:`conf-scripts`
...@@ -68,7 +68,6 @@ special targets: ...@@ -68,7 +68,6 @@ special targets:
.. _ost_l: http://www.OpenStructure.org .. _ost_l: http://www.OpenStructure.org
.. _ost_s: http://www.OpenStructure.org
.. _cmake: http://www.cmake.org/ .. _cmake: http://www.cmake.org/
.. _python: https://www.python.org/ .. _python: https://www.python.org/
.. _boost: http://www.boost.org/ .. _boost: http://www.boost.org/
......
...@@ -269,7 +269,6 @@ version control, create a couple of files which are always needed. ...@@ -269,7 +269,6 @@ version control, create a couple of files which are always needed.
.. code-block:: console .. code-block:: console
$ touch sidechains/pymod/__init__.py $ touch sidechains/pymod/__init__.py
$ echo "FOO" >> sidechains/doc/index.rst
$ echo ":mod:\`~promod3.sidechains\` - ProMod3 side chain optimiser" >> sidechains/doc/index.rst $ echo ":mod:\`~promod3.sidechains\` - ProMod3 side chain optimiser" >> sidechains/doc/index.rst
$ echo "================================================================================" >> sidechains/doc/index.rst $ echo "================================================================================" >> sidechains/doc/index.rst
$ $
...@@ -330,7 +329,7 @@ a couple of examples around in this repository. Here is the most basic ...@@ -330,7 +329,7 @@ a couple of examples around in this repository. Here is the most basic
:file:`CMakeLists.txt`: :file:`CMakeLists.txt`:
.. code-block:: cmake .. code-block:: cmake
:linenos: :linenos:
set(SIDECHAINS_PYMOD set(SIDECHAINS_PYMOD
__init__.py __init__.py
...@@ -348,8 +347,8 @@ The final step towards |cmake| is to register your module's directory in the ...@@ -348,8 +347,8 @@ The final step towards |cmake| is to register your module's directory in the
top level :file:`CMakeLists.txt`: top level :file:`CMakeLists.txt`:
.. code-block:: cmake .. code-block:: cmake
:linenos: :linenos:
:emphasize-lines: 80 :emphasize-lines: 80
#------------------------------------------------------------------------------- #-------------------------------------------------------------------------------
# Author: Bienchen # Author: Bienchen
...@@ -481,14 +480,90 @@ a new configuration script. The following example assumes |fedora| 19. ...@@ -481,14 +480,90 @@ a new configuration script. The following example assumes |fedora| 19.
From this point, :command:`make` should work and you could start adding your From this point, :command:`make` should work and you could start adding your
files to the repository using ``git add``. files to the repository using ``git add``.
Up to now, we did not cover the :file:`tests` branch of a new module. But its
good practice to develop new functionality along tests and that right from the
beginning. At some point, new code needs testing anyway to see if it does what
it should, so just do this by writing unit tests. Test sources are stored in
files with a prefix :file:`test_` and usually come per submodule instead of
sporting a single monolithic :file:`test_sidechains.py`.
|python| code is evaluated using its own
:py_docs:`unit testing framework <library/unittest.html>` with a little help
from |ost_s|_. The basic scheme is to import your module, subclass
:class:`unittest.TestCase` and make the whole file runnable as script using the
most common |nameattr|_ attribute. A file :file:`tests/test_something.py` could
look like this, carrying a single test case:
.. testcode:: promod3unittest
:hide:
import unittest
class something():
@staticmethod
def Else():
return 1
class SomethingTests(unittest.TestCase):
def testFileExistsFalse(self):
self.assertEquals(something.Else(), 1)
if __name__ == "__builtin__":
suite = unittest.TestLoader().loadTestsFromTestCase(SomethingTests)
unittest.TextTestRunner().run(suite)
.. code-block:: python
:linenos:
import unittest
from promod3.sidechains import something
class SomethingTests(unittest.TestCase):
def testFileExistsFalse(self):
self.assertEquals(something.Else(), 1)
if __name__ == "__main__":
from ost import testutils
testutils.RunTests()
To hook up your tests with ``make codetest`` (and to create a
``test_something.py_run`` target), everything has to be introduced to |cmake|.
First, tell |cmake| to search :file:`tests` for a :file:`CMakeLists.txt` file
by extending the list of sub-directories in :file:`sidechains/CMakeLists.txt`:
.. code-block:: cmake
:linenos:
add_subdirectory(pymod)
add_subdirectory(doc)
add_subdirectory(tests)
Then fill :file:`sidechains/tests/CMakeLists.txt` with your new test script and
``make`` will recognise the changes next time it is run and fix the rest for
you.
.. code-block:: cmake
:linenos:
set(SIDECHAINS_UNIT_TESTS
test_something.py
)
promod3_unittest(MODULE sidechains SOURCES "${SIDECHAINS_UNIT_TESTS}")
Now tests should be available by ``make check``, ``make codetest`` and
``make test_something.py_run``.
.. _restructuredtext: http://docutils.sourceforge.net/rst.html .. _restructuredtext: http://docutils.sourceforge.net/rst.html
.. |fedora| replace:: Fedora .. |fedora| replace:: Fedora
.. |nameattr| replace:: :attr:`__name__`
.. LocalWords: cmake hotfix doctest linkcheck rebase BRANCHNAME rebasing py .. LocalWords: cmake hotfix doctest linkcheck rebase BRANCHNAME rebasing py
.. LocalWords: CMakeLists txt rst pymod init submodule src restructuredtext .. LocalWords: CMakeLists txt rst pymod init submodule src restructuredtext
.. LocalWords: makefiles formatters Changelog codetest promod sidechains io .. LocalWords: makefiles formatters Changelog codetest promod sidechains io
.. LocalWords: mkdir linenos subdirectory abrv emphasize CXX GNUCXX gcc fno .. LocalWords: mkdir linenos subdirectory abrv emphasize CXX GNUCXX gcc fno
.. LocalWords: ARGS endif OPTIMIZE LIBEXEC Wno DIRS dirs subdirs config dbg .. LocalWords: ARGS endif OPTIMIZE LIBEXEC Wno DIRS dirs subdirs config dbg
.. LocalWords: changelog Optimized DOPTIMIZE gitignore cd conf .. LocalWords: changelog Optimized DOPTIMIZE gitignore cd conf subtree attr
.. LocalWords: unittest TestCase nameattr testcode staticmethod builtin
.. LocalWords: SomethingTests testFileExistsFalse testutils RunTests
...@@ -88,9 +88,9 @@ put a <tt class="docutils literal"><span class="pre">-D</span></tt> in front of ...@@ -88,9 +88,9 @@ put a <tt class="docutils literal"><span class="pre">-D</span></tt> in front of
<p>Here is a list of more options used within ProMod3:</p> <p>Here is a list of more options used within ProMod3:</p>
<ul class="simple"> <ul class="simple">
<li><tt class="docutils literal"><span class="pre">DISABLE_DOCUMENTATION</span></tt> Don&#8217;t build documentation, don&#8217;t search for Sphinx</li> <li><tt class="docutils literal"><span class="pre">DISABLE_DOCUMENTATION</span></tt> Don&#8217;t build documentation, don&#8217;t search for Sphinx</li>
<li><tt class="docutils literal"><span class="pre">DISABLE_DOCTEST</span></tt> Don&#8217;t run example code from documentation on &#8216;make check&#8217; <li><tt class="docutils literal"><span class="pre">DISABLE_DOCTEST</span></tt> Don&#8217;t run example code from documentation on
(implicit by <tt class="docutils literal"><span class="pre">DISABLE_DOCUMENTATION</span></tt>)</li> <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt> (implicit by <tt class="docutils literal"><span class="pre">DISABLE_DOCUMENTATION</span></tt>)</li>
<li><tt class="docutils literal"><span class="pre">DISABLE_LINKCHECK</span></tt> Don&#8217;t test links from documentation on &#8216;make check <li><tt class="docutils literal"><span class="pre">DISABLE_LINKCHECK</span></tt> Don&#8217;t test links from documentation on <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt>
(implicit by <tt class="docutils literal"><span class="pre">DISABLE_DOCUMENTATION</span></tt>)</li> (implicit by <tt class="docutils literal"><span class="pre">DISABLE_DOCUMENTATION</span></tt>)</li>
</ul> </ul>
<p>Instead of calling CMake by yourself, there is the <tt class="file docutils literal"><span class="pre">conf-scripts</span></tt> <p>Instead of calling CMake by yourself, there is the <tt class="file docutils literal"><span class="pre">conf-scripts</span></tt>
...@@ -186,7 +186,7 @@ configuration also Sphinx with the <tt class="docutils literal"><span class="pre ...@@ -186,7 +186,7 @@ configuration also Sphinx with the <tt class="docutils literal"><span class="pre
</div> </div>
<div class="footer"> <div class="footer">
&copy; Copyright 2013, Bienchen. &copy; Copyright 2013, Bienchen.
Last updated on May 26 14:31, 2014. Last updated on Jun 14 19:22, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
</div> </div>
</body> </body>
......
...@@ -127,7 +127,7 @@ ...@@ -127,7 +127,7 @@
</div> </div>
<div class="footer"> <div class="footer">
&copy; Copyright 2013, Bienchen. &copy; Copyright 2013, Bienchen.
Last updated on May 26 13:39, 2014. Last updated on Jun 14 18:21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
</div> </div>
</body> </body>
......
This diff is collapsed.
...@@ -217,7 +217,7 @@ shell. <tt class="docutils literal"><span class="pre">0</span></tt> is tradition ...@@ -217,7 +217,7 @@ shell. <tt class="docutils literal"><span class="pre">0</span></tt> is tradition
</div> </div>
<div class="footer"> <div class="footer">
&copy; Copyright 2013, Bienchen. &copy; Copyright 2013, Bienchen.
Last updated on May 26 13:39, 2014. Last updated on Jun 14 18:21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
</div> </div>
</body> </body>
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment