Creating project-specific skelleton for Sphinx manual

CHANGELOG.rst

@@ -0,0 +1,9 @@
+=========
+Changelog
+=========
+
+--------------------------------
+v0.1-SNAPSHOT (work in progress)
+--------------------------------
+
+- Everything is new.

manual/requirements.txt

@@ -0,0 +1,3 @@
+# The packages required to build the documentation.
+sphinx
+sphinx-rtd-theme

manual/source/authors.rst

@@ -0,0 +1,10 @@
+.. _authors:
+
+=======
+Authors
+=======
+
+- Sebastian Bauer
+- Peter N. Robinson
+- Sebastian Koehler
+- Manuel Holtgrewe

manual/source/conf.py

@@ -82,7 +82,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

manual/source/contributing.rst

@@ -0,0 +1,192 @@
+.. _contributing:
+
+============
+Contributing
+============
+
+Contributions are welcome, and they are greatly appreciated!
+Every little bit helps, and credit will always be given.
+
+You can contribute in many ways:
+
+----------------------
+Types of Contributions
+----------------------
+
+
+Report Bugs
+===========
+
+Report bugs at https://github.com/phenomics/ontolib/issues
+
+If you are reporting a bug, please include:
+
+* Your operating system name and version.
+* Any details about your local setup that might be helpful in troubleshooting.
+* Detailed steps to reproduce the bug.
+
+
+Fix Bugs
+========
+
+Look through the Github issues for bugs.
+If you want to start working on a bug then please write short message on the issue tracker to prevent duplicate work.
+
+
+Implement Features
+==================
+
+Look through the Github issues for features.
+If you want to start working on an issue then please write short message on the issue tracker to prevent duplicate work.
+
+
+Write Documentation
+===================
+
+OntoLib could always use more documentation, whether as part of the official vcfpy docs, in docstrings, or even on the web in blog posts, articles, and such.
+
+OntoLib uses `Sphinx <https://sphinx-doc.org>`_ for the user manual (that you are currently reading).
+See `doc_guidelines` on how the documentation reStructuredText is used.
+See `doc_setup` on creating a local setup for building the documentation.
+
+
+Submit Feedback
+===============
+
+The best way to send feedback is to file an issue at https://github.com/phenomics/ontolib/issues
+
+If you are proposing a feature:
+
+* Explain in detail how it would work.
+* Keep the scope as narrow as possible, to make it easier to implement.
+* Remember that this is a volunteer-driven project, and that contributions are welcome :)
+
+
+.. _doc_guidelines:
+
+------------------------
+Documentation Guidelines
+------------------------
+
+For the documentation, please adhere to the following guidelines:
+
+- Put each sentence on its own line, this makes tracking changes through Git SCM easier.
+- Provide hyperlink targets, at least for the first two section levels.
+- Use the section structure from below.
+
+::
+
+    .. heading_1:
+
+    =========
+    Heading 1
+    =========
+
+
+    .. heading_2:
+
+    ---------
+    Heading 2
+    ---------
+
+
+    .. heading_3:
+
+    Heading 3
+    =========
+
+
+    .. heading_4:
+
+    Heading 4
+    ---------
+
+
+    .. heading_5:
+
+    Heading 5
+    ~~~~~~~~~
+
+
+    .. heading_6:
+
+    Heading 6
+    :::::::::
+
+
+.. _doc_setup:
+
+-------------------
+Documentation Setup
+-------------------
+
+For building the documentation, you have to install the Python program Sphinx.
+This is best done in a virtual environment.
+The following assumes you have a working Python 3 setup.
+
+Use the following steps for installing Sphinx and the dependencies for building the OntoLib documentation:
+
+.. code-block:: console
+
+    $ cd ontolib/manual
+    $ virtualenv -p python3 .venv
+    $ source .venv/bin/activate
+    $ pip install --upgrade -r requirements.txt
+
+Use the following for building the documentation.
+The first two lines is only required for loading the virtualenv.
+Afterwards, you can always use ``make html`` for building.
+
+.. code-block:: console
+
+    $ cd ontolib/manual
+    $ source .venv/bin/activate
+    $ make html  # rebuild for changed files only
+    $ make clean && make html  # force rebuild
+
+
+------------
+Get Started!
+------------
+
+Ready to contribute?
+First, create your Java/Documentation development setup as described in `install_from_source`/`doc_setup`.
+
+1. Fork the `OntoLib` repo on GitHub.
+2. Clone your fork locally::
+
+    $ git clone [email protected]:your_name_here/ontolib.git
+
+3. Create a branch for local development::
+
+    $ git checkout -b name-of-your-bugfix-or-feature
+
+   Now you can make your changes locally.
+
+5. When you're done making your changes, make sure that the build runs through.
+   For Java:
+
+    $ mvn package
+
+   For documentation:
+
+    $ make clean && make html
+
+6. Commit your changes and push your branch to GitHub::
+
+    $ git add .
+    $ git commit -m "Your detailed description of your changes."
+    $ git push origin name-of-your-bugfix-or-feature
+
+7. Submit a pull request through the GitHub website.
+
+
+-----------------------
+Pull Request Guidelines
+-----------------------
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+2. If the pull request adds functionality, the docs should be updated.
+3. Describe your changes in the ``CHANGELOG.md`` file.

manual/source/history.rst

@@ -0,0 +1,3 @@
+.. _changelog:
+
+.. include:: ../../CHANGELOG.rst

manual/source/index.rst

@@ -1,20 +1,55 @@
-.. OntoLib documentation master file, created by
-   sphinx-quickstart on Sun Jul 23 15:14:30 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+==================================
+Welcome to OntoLib's Documentation
+==================================
 
-Welcome to OntoLib's documentation!
-===================================
+OntoLib is a modern Java (version 8 and above) library for working with (biological) ontologies.
+You can easily load an OBO file into an `Ontology` object and work with it in your code.
+Additionally, there is special support for important biological entities such as HPO and GO that make working with them easier by making important sub ontologies and terms more accessible.
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+-------------
+Quick Example
+-------------
+
+  .. code-block:: java
+
+    HpoOntology hpo;
+    try (HpoOboParser hpoOboParser = new HpoOboParser(new File("hp.obo"))) {
+      hpo = hpoOboParser.parse();
+    } except (IOException e) {
+      System.exit(1);
+    }
+
+    Ontology<HpoTerm, HpoTermRelation> abnormalPhenoSubOntology =
+      hpo.getPhenotypicAbnormalitySubOntology();
+    for (TermId termId : abnormalPhenoSubOntology.getNonObsoleteTermIds()) {
+      // ...
+    }
 
+--------
+Feedback
+--------
 
+The best place to leave feedback, ask questions, and report bugs is the `OntoLib Issue Tracker <https://github.com/phenomics/ontolib/issues>`_.
 
-Indices and tables
-==================
+.. toctree::
+    :caption: Installation & Tutorial
+    :name: tutorial
+    :maxdepth: 1
+    :hidden:
+
+    install
+    tutorial_io
+    tutorial_hpo
+    tutorial_annotation
+    tutorial_similarity
+
+.. toctree::
+    :caption: Project Info
+    :name: project-info
+    :maxdepth: 1
+    :hidden:
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+    contributing
+    authors
+    history
+    license