<!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="Content-Type" content="text/html; charset=utf-8" />
<title>About These Documents — v2.1.0-beta</title>
<link rel="stylesheet" href="_static/dataone.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.1.0-beta',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/mathjax_pre.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="//cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML"></script>
<script type="text/javascript" src="_static/sidebar.js"></script>
<link rel="author" title="About these documents" href="#" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Glossary" href="glossary.html" />
<link rel="prev" title="Acknowledgements" href="acknowledgements.html" />
<link media="only screen and (max-device-width: 480px)" href="_static/small_dataone.css" type= "text/css" rel="stylesheet" />
</head>
<body role="document">
<div class="version_notice">
<p>
<span class='bold'>Warning:</span> These documents are under active
development and subject to change (version 2.1.0-beta).<br />
The latest release documents are at:
<a href="https://purl.dataone.org/architecture">https://purl.dataone.org/architecture</a>
</p>
</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"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="glossary.html" title="Glossary"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="acknowledgements.html" title="Acknowledgements"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html"></a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="about-these-documents">
<h1>About These Documents<a class="headerlink" href="#about-these-documents" title="Permalink to this headline">¶</a></h1>
<p>These documents are generated using <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> for the overall document
processing and generation, and <a class="reference external" href="http://plantuml.sourceforge.net">PlantUML</a> for most of the UML diagrams.</p>
<div class="section" id="editing-content">
<h2>Editing Content<a class="headerlink" href="#editing-content" title="Permalink to this headline">¶</a></h2>
<p>All of these documents are formatted in <a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">reStructuredText</a>, formatted plain
text that is similar to the plain text formatting used in wiki pages. The
formatting guidelines for Sphinx are available at
<a class="reference external" href="http://sphinx.pocoo.org/contents.html">http://sphinx.pocoo.org/contents.html</a></p>
<p>Portions of content, specifically all the individual function and exception
descriptions, are maintained in an Excel spreadsheet (best edited using
OpenOffice Calc). The <a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">reStructuredText</a> descriptions of the methods and
exceptions is generated by processing the content in the spreadsheet with a
python script “ihwd.py” located in the tools folder.</p>
<p>All content should be saved as UTF-8 encoded text using UNIX® style new lines.
White space and indentation is part of the formatting for reStructuredText.
Please be consistent with the use of soft tabs (2 spaces per tab).</p>
<p><a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">reStructuredText</a> can be edited with any plain text editor. These documents
have been edited mainly with <a class="reference external" href="http://macromates.com/">TextMate</a> on OS X, which offers a preview feature
when the <a class="reference external" href="https://github.com/textmate/restructuredtext.tmbundle">reStructuredText bundle</a> is installed. Other editors that work well
for editing <a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">reStructuredText</a> are jEdit and Komodo Edit. There are also
various plugins available for editors to assist with reStructuredText
formatting.</p>
<p>Follow the normal procedures for working with the subversion repository. After
checking in, your edits should appear in the <a class="reference external" href="http://129.24.0.15/ArchitectureDocs/">built out version</a> of the docs
within five minutes.</p>
<p>The convention for different levels of heading used in these documents is:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">===</span> <span class="n">Level</span> <span class="mi">1</span>
<span class="o">---</span> <span class="n">Level</span> <span class="mi">2</span>
<span class="o">~~~</span> <span class="n">Level</span> <span class="mi">3</span>
<span class="o">...</span> <span class="n">Level</span> <span class="mi">4</span>
</pre></div>
</div>
</div>
<div class="section" id="building-the-documentation">
<h2>Building the Documentation<a class="headerlink" href="#building-the-documentation" title="Permalink to this headline">¶</a></h2>
<p><a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> is required to build the design documents from the source. A couple of
Sphinx extensions are included with the subversion checkout of these documents
(in <code class="docutils literal"><span class="pre">tools/docutils/rst_directives</span></code>). Portions of Sphinx and the <a class="reference external" href="http://plantuml.sourceforge.net">PlantUML</a>
extension have a dependency of <a class="reference external" href="http://www.graphviz.org/">Graphviz</a>, and this will need to be installed
in order to build the documents. The <a class="reference external" href="http://code.google.com/p/rst2pdf/">rst2pdf</a> library is required to build the pdf version of the documents.</p>
<div class="section" id="setting-up-a-build-environment">
<h3>Setting up a Build Environment<a class="headerlink" href="#setting-up-a-build-environment" title="Permalink to this headline">¶</a></h3>
<p>The following general instructions apply for Ubuntu linux. Adjust the commands
as necessary for your OS (and please update these docs to help others in the
process). It is assumed that Python >= 2.6 and Java are available.</p>
<ol class="arabic">
<li><p class="first">Install graphviz:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ sudo apt-get install graphviz
</pre></div>
</div>
</li>
<li><p class="first">Install Sphinx (latest version):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ sudo easy_install -U Sphinx
</pre></div>
</div>
</li>
<li><p class="first">(Optional) Install rst2pdf:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ sudo easy_install -U rst2pdf
</pre></div>
</div>
</li>
<li><p class="first">(Optional) Edits to the method descriptions in the excel spreadsheet
(<code class="docutils literal"><span class="pre">MethodCrossReference.xls</span></code>) require regeneration of some portions of the
documentation, which requires a couple of Python libraries (xlrd and xlwt):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ sudo easy_install xlrd xlwt
</pre></div>
</div>
</li>
<li><p class="first">Checkout a copy of the documentation from subversion:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ svn co https://repository.dataone.org/documents/Projects/cicore/architecture/api-documentation
</pre></div>
</div>
</li>
<li><p class="first">Build the documents:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ cd api-documentation
$ make html
</pre></div>
</div>
<p>The documents will be available in <code class="docutils literal"><span class="pre">build/html</span></code>, with <code class="docutils literal"><span class="pre">index.html</span></code> being the root document.</p>
</li>
</ol>
<ul>
<li><p class="first">If changes are made to <code class="docutils literal"><span class="pre">MethodCrossReference.xls</span></code>, then an additional make
step is required:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ cd api-documentation
$ make generate
$ make html
</pre></div>
</div>
</li>
<li><p class="first">If changes to plantuml diagrams have been made then it will be necessary to
regenerate the associated .png images. This can be done using <em>make</em>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ cd api-documentation
$ make plantuml
$ make html
</pre></div>
</div>
<p>The plantuml diagram generation can take a while. There are three sub-tasks
for <em>make</em>, plantuml_source, plantuml_usecase, and plantuml_types which can
be used to build diagrams under the <em>source/design</em>,
<em>source/design/UseCases</em>, or <em>source/apis</em> folders respectively.</p>
</li>
</ul>
<ol class="arabic" start="7">
<li><p class="first">To build a PDF version of the documents.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ make pdf
</pre></div>
</div>
<p>Note that the PDF generator can be quite fickle, and may require some tweaking to work.</p>
</li>
<li><p class="first">To build an ePub version of the documents:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ make epub
</pre></div>
</div>
</li>
</ol>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="http://dataone.org">
<img class="logo" src="_static/dataone_logo.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">About These Documents</a><ul>
<li><a class="reference internal" href="#editing-content">Editing Content</a></li>
<li><a class="reference internal" href="#building-the-documentation">Building the Documentation</a><ul>
<li><a class="reference internal" href="#setting-up-a-build-environment">Setting up a Build Environment</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation Overview</a><ul>
<li>Previous: <a href="acknowledgements.html" title="previous chapter">Acknowledgements</a></li>
<li>Next: <a href="glossary.html" title="next chapter">Glossary</a></li>
</ul></li>
</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
<div id="copyright">
© Copyright <a href="http://www.dataone.org">2009-2017, DataONE</a>.
[ <a href="_sources/about.txt"
rel="nofollow">Page Source</a> |
<a href='https://redmine.dataone.org/projects/d1/repository/changes/documents/Projects/cicore/architecture/api-documentation/source/about.txt'
rel="nofollow">Revision History</a> ]
</div>
<div id="acknowledgement">
<p>This material is based upon work supported by the National Science Foundation
under Grant Numbers <a href="http://www.nsf.gov/awardsearch/showAward?AWD_ID=0830944">083094</a> and <a href="http://www.nsf.gov/awardsearch/showAward?AWD_ID=1430508">1430508</a>.</p>
<p>Any opinions, findings, and conclusions or recommendations expressed in this
material are those of the author(s) and do not necessarily reflect the views
of the National Science Foundation.</p>
</div>
</div>
<!--
<hr />
<div id="HCB_comment_box"><a href="http://www.htmlcommentbox.com">HTML Comment Box</a> is loading comments...</div>
<link rel="stylesheet" type="text/css" href="_static/skin.css" />
<script type="text/javascript" language="javascript" id="hcb">
/*<! -*/
(function()
{s=document.createElement("script");
s.setAttribute("type","text/javascript");
s.setAttribute("src", "http://www.htmlcommentbox.com/jread?page="+escape((typeof hcb_user !== "undefined" && hcb_user.PAGE)||(""+window.location)).replace("+","%2B")+"&mod=%241%24wq1rdBcg%24Gg8J5iYSHJWwAJtlYu/yU."+"&opts=21407&num=10");
if (typeof s!="undefined") document.getElementsByTagName("head")[0].appendChild(s);})();
/* ->*/
</script>
-->
</body>
</html>