Addition of Breathe

#114
Compilation details in readme.txt in the docs folder.
Added Breathe and doxygen folders

README.md

@@ -13,4 +13,6 @@ Malins A, Williams SR, Eggers J & Royall CP "Identification of Structure in Cond
 
 This software is distributed under the GNU General Public License v3. For more details see the LICENSE file.
 
-This software makes use of the iniparser library (https://github.com/ndevilla/iniparser/) which is distributed under the MIT License.
+This software makes use of libraries released under other licenses:
+* The iniparser library (https://github.com/ndevilla/iniparser/) which is distributed under the MIT license.
+* The Breathe package (https://github.com/michaeljones/breathe) which is distributed under the BSD license

docs/README.md

@@ -2,8 +2,24 @@
 
 The documentation for the TCC is generated using the Sphinx Python package.
 
-Documentation is written in reStructuredText format and compiled by the Sphinx package into a HTML source. At compilation time Sphinx also scrapes docstrings from the Python scripts and adds these to the documentation. Extraction of docstrings from the C source is planned but not yet in place.
+Documentation is written in reStructuredText format and compiled by the Sphinx package into a HTML source. At compilation time Sphinx also scrapes docstrings from the Python scripts and adds these to the documentation.
 
-To compile the documentation after a change use the command `sphinx-build -b html ./source ./html` from the docs folder.
+C docstrings are scraped by Doxygen to XML format and then imported into sphinx using the Breathe package for Sphinx.
 
-Once a commit is made to the master branch the docs folder is mirrored to https://royallgroup.github.io/TCC/, thus providing an online version of the documentation.
+Requrements
+=============
+
+Doxygen (http://www.doxygen.nl/)
+Sphinx (http://www.sphinx-doc.org/en/master/)
+
+Compiling documentation
+=========================
+
+To recompile the documentation after a change, from the docs folder use the commands::
+
+cd doxygen
+doxygen
+cd ..
+sphinx-build -b html ./source ./html
+
+Once a commit is made to the master branch the docs folder is mirrored to https://royallgroup.github.io/TCC/, providing an online version of the documentation.

docs/doxygen/.gitignore

@@ -0,0 +1,2 @@
+xml/
+html/

docs/html/_sources/clusters.rst.txt

@@ -0,0 +1,25 @@
+Running the TCC
+=================
+
+Running the TCC requires 4 files, the binary, inputparameters.ini, box.txt and an input xyz file.
+
+* A binary called ``tcc`` will be generated in the bin folder.
+* inputparameters.ini sets some required parameters for the analysis, an example is given in the samples folder. Details of the parameters are given on the ::inputparameters page.
+* box.txt gives the boundaries of the simulation box for systems with periodic boundaries. An example can be found in the examples folder. The specification of the box file is given below.
+* The input configuration should be given as an XYZ file, it is not required that the XYZ file have the same number of particles in each frame. The TCC is limited to reading in a maximum of 1000 xyz frames.
+
+Specifying periodic boundary conditions
+----------------------------------------
+
+* If the system does not have periodic boundary conditions set PBCs to 0 in inputparamers.in
+* For any system with periodic boundaries the boundaries are stored in the box file specified in inputparamers.in. The first line of the box file should be a title line (usually column headings) which will be ignored. The specification of coordinates is detailed below for each system type.
+* For NVT systems set the box_type parameter in inputparamers.in to 1. The box size will be read at TCC initialisation from the second line of the box.txt file (first line is a comment). The syntax is "timestep sidex sidey sidez" where timestep = 0 and sidex sidey and sidez are the x y and z box side lengths.
+* For NPT systems set the box_type parameter in inputparamers.in to 2. The box size will be read each xyz frame from the box.txt file. The syntax is "timestep sidex sidey sidez" with each timestep on a new line. There must be at least as many timesteps as frames in the xyz file.
+* For systems with triclinic boundary conditions with tilt, set the box_type parameter in inputparamers.in to 3. The box size will be read each xyz frame from the box.txt file. The syntax is "timestep sidex sidey sidez tilt" where the tilt has a sign.
+
+Excluding clusters from analysis
+***********************************
+
+Sometimes it is not necessary to detect all possible cluster types, some clusters may be more interesting than others. For example in the hard sphere system 10B and 13A are of particular interest since they are locally favoured structures. Selecting only a subset of clusters can significantly increase the speed of the TCC.
+
+To analyse only a subset of the clusters set the **analyse_all_clusters** parameter in the ``inputparamters.ini`` file to 0. In the directory the where the TCC will execute, place the ``clusters_to_analyse.ini`` file - an example can be found in the examples folder. It is only necessary to specify the clusters you want to detect, any prerequisite smaller clusters will be automatically selected.

docs/html/_sources/index.rst.txt

@@ -15,7 +15,8 @@ This documentation gives information about the latest version of the Topological
    python_scripts
    xyz_specification
    tcc_python_scripts
-
+   tcc_cluster_source
+
 Indices and tables
 ==================
 

docs/html/_sources/tcc_cluster_source.rst.txt

@@ -0,0 +1,5 @@
+Cluster Descriptions
+===========================
+
+.. doxygenindex::
+   :project: TCC

docs/html/clusters.html

@@ -0,0 +1,121 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>Running the TCC &#8212; TCC  documentation</title>
+    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" /> 
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">TCC  documentation</a> &#187;</li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+
+  <div class="section" id="running-the-tcc">
+<h1>Running the TCC<a class="headerlink" href="#running-the-tcc" title="Permalink to this headline">¶</a></h1>
+<p>Running the TCC requires 4 files, the binary, inputparameters.ini, box.txt and an input xyz file.</p>
+<ul class="simple">
+<li>A binary called <code class="docutils literal notranslate"><span class="pre">tcc</span></code> will be generated in the bin folder.</li>
+<li>inputparameters.ini sets some required parameters for the analysis, an example is given in the samples folder. Details of the parameters are given on the ::inputparameters page.</li>
+<li>box.txt gives the boundaries of the simulation box for systems with periodic boundaries. An example can be found in the examples folder. The specification of the box file is given below.</li>
+<li>The input configuration should be given as an XYZ file, it is not required that the XYZ file have the same number of particles in each frame. The TCC is limited to reading in a maximum of 1000 xyz frames.</li>
+</ul>
+<div class="section" id="specifying-periodic-boundary-conditions">
+<h2>Specifying periodic boundary conditions<a class="headerlink" href="#specifying-periodic-boundary-conditions" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>If the system does not have periodic boundary conditions set PBCs to 0 in inputparamers.in</li>
+<li>For any system with periodic boundaries the boundaries are stored in the box file specified in inputparamers.in. The first line of the box file should be a title line (usually column headings) which will be ignored. The specification of coordinates is detailed below for each system type.</li>
+<li>For NVT systems set the box_type parameter in inputparamers.in to 1. The box size will be read at TCC initialisation from the second line of the box.txt file (first line is a comment). The syntax is “timestep sidex sidey sidez” where timestep = 0 and sidex sidey and sidez are the x y and z box side lengths.</li>
+<li>For NPT systems set the box_type parameter in inputparamers.in to 2. The box size will be read each xyz frame from the box.txt file. The syntax is “timestep sidex sidey sidez” with each timestep on a new line. There must be at least as many timesteps as frames in the xyz file.</li>
+<li>For systems with triclinic boundary conditions with tilt, set the box_type parameter in inputparamers.in to 3. The box size will be read each xyz frame from the box.txt file. The syntax is “timestep sidex sidey sidez tilt” where the tilt has a sign.</li>
+</ul>
+<div class="section" id="excluding-clusters-from-analysis">
+<h3>Excluding clusters from analysis<a class="headerlink" href="#excluding-clusters-from-analysis" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes it is not necessary to detect all possible cluster types, some clusters may be more interesting than others. For example in the hard sphere system 10B and 13A are of particular interest since they are locally favoured structures. Selecting only a subset of clusters can significantly increase the speed of the TCC.</p>
+<p>To analyse only a subset of the clusters set the <strong>analyse_all_clusters</strong> parameter in the <code class="docutils literal notranslate"><span class="pre">inputparamters.ini</span></code> file to 0. In the directory the where the TCC will execute, place the <code class="docutils literal notranslate"><span class="pre">clusters_to_analyse.ini</span></code> file - an example can be found in the examples folder. It is only necessary to specify the clusters you want to detect, any prerequisite smaller clusters will be automatically selected.</p>
+</div>
+</div>
+</div>
+
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table Of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Running the TCC</a><ul>
+<li><a class="reference internal" href="#specifying-periodic-boundary-conditions">Specifying periodic boundary conditions</a><ul>
+<li><a class="reference internal" href="#excluding-clusters-from-analysis">Excluding clusters from analysis</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/clusters.rst.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3>Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" />
+      <input type="submit" value="Go" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    </div>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="right" >
+          <a href="py-modindex.html" title="Python Module Index"
+             >modules</a> |</li>
+        <li class="nav-item nav-item-0"><a href="index.html">TCC  documentation</a> &#187;</li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2018, Peter Crowther.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+    </div>
+  </body>
+</html>