Merge pull request #8 from edmondchuc/master

Documentation in Sphinx

README.rst

@@ -0,0 +1,104 @@
+Welcome to pyLDAPI
+==================
+
+*A very small module to add Linked Data API functionality to a Python Flask installation*.
+
+
+
+What is it?
+===========
+
+This module contains only a small Python module which is intended to be added (imported) into a `Python Flask`_ installation in order to add a series of extra functions to endpoints to the ones defined by you as a Flask user (URL routes).
+
+.. _Python Flask: http://flask.pocoo.org/
+
+An API using this module will get:
+
+* an *alternates view* for each *Register* and *Object* that the API delivers
+   * if the API declares the appropriate *model views* for each item
+* a *Register of Registers*
+   * a start-up function that auto-generates a Register of Registers is run when the API is launched.
+* a basic, over-writeable template for Registers' HTML & RDF
+
+
+
+Definitions
+===========
+
+Alternates View
+---------------
+The *model view* that lists all other views. This API uses the definition of *alternates view* presented at `https://promsns.org/def/alt`_.
+
+.. _https://promsns.org/def/alt: https://promsns.org/def/alt
+
+Linked Data Principles
+----------------------
+The principles of making things available over the internet in both human and machine-readable forms. Codified by the World Wide Web Consortium. See `https://www.w3.org/standards/semanticweb/data`_.
+
+.. _https://www.w3.org/standards/semanticweb/data: https://www.w3.org/standards/semanticweb/data
+
+
+Model View
+----------
+A set of properties of a Linked Data object codified according to a standard or profile of a standard.
+
+Object
+------
+Any individual thing delivered according to *Linked Data* principles.
+
+Register
+--------
+A simple listing of URIs of objects, delivered according to *Linked Data principles*.
+
+Register of Registers
+---------------------
+A *register* that lists all other registers which this API provides.
+
+
+
+pyLDAPI in action
+=================
+
+* Register of Media Types
+   * `https://w3id.org/mediatype/`_
+
+.. _https://w3id.org/mediatype/: https://w3id.org/mediatype/
+
+* Linked Data version of the Geocoded National Address File
+   * `http://linked.data.gov.au/dataset/gnaf`_
+
+.. _http://linked.data.gov.au/dataset/gnaf: http://linked.data.gov.au/dataset/gnaf
+
+
+
+Licence
+=======
+
+This is licensed under GNU General Public License (GPL) v3.0. See the `LICENSE deed`_ for more details.
+
+.. _LICENSE deed: https://raw.githubusercontent.com/RDFLib/pyLDAPI/master/LICENSE
+
+
+
+Contact
+=======
+
+Nicholas Car (lead)
+-------------------
+| *Senior Experimental Scientist*
+| `CSIRO Land and Water`_
+| `[email protected]`_
+| `http://orcid.org/0000-0002-8742-7730`_
+
+.. _[email protected]: [email protected]
+.. _http://orcid.org/0000-0002-8742-7730: http://orcid.org/0000-0002-8742-7730
+
+Ashley Sommer (senior developer)
+--------------------------------
+| *Informatics Software Engineer*
+| `CSIRO Land and Water`_
+| `[email protected]`_
+
+.. _[email protected]: [email protected]
+
+.. _CSIRO Land and Water: https://www.csiro.au/en/Research/LWF

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,20 @@
+# Building the Documentation
+* Ensure all requirements are met in the **requirements.txt** file.
+* Using the command line/terminal, `cd` into **docs/**`.
+* Perform `make clean`
+* Perform `make html`
+* With python3 installed, run `python -m http.server 5000` in the **docs/build/html/** directory.
+* Go to `localhost:5000` to see the result.
+
+# Seeing changes while editing
+Simply use `make html` to update the textual changes and refresh the browser.
+
+Note: To see changes for the toctree, the documents must be generated again. In this instance, one would do as follows:
+* `ctrl + c` to stop the http server
+* `make clean`
+* `make html`
+* `python -m http.server 5000` to start the server again
+
+# PyCharm optional but recommended settings
+* https://www.jetbrains.com/help/pycharm/documenting-source-code.html
+* https://www.jetbrains.com/help/pycharm/restructured-text.html

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/source/alternates_template.rst

@@ -0,0 +1,53 @@
+Alternates template
+===================
+
+Example of a generic alternates template:
+
+.. code-block:: HTML
+
+    {% extends "layout.html" %}
+    {% block content %}
+        <h1>{{ register_name }} Linked Data API</h1>
+        {% if class_uri %}
+            <h3>Alternates view of a <a href="{{ class_uri }}">{{ class_uri }}</a></h3>
+        {% else %}
+            <h3>Alternates view</h3>
+        {% endif %}
+        {% if instance_uri %}
+            <h3>Instance <a href="{{ instance_uri }}">{{ instance_uri }}</a></h3>
+        {% endif %}
+        <p>Default view: <a href="{{ request.base_url }}?_view={{ default_view_token }}">{{ default_view_token }}</a></p>
+        <table class="pretty">
+        <tr><th>View</th><th>Formats</th><th>View Desc.</th><th>View Namespace</th></tr>
+        {% for v, vals in views.items() %}
+                <tr>
+                    <td><a href="{{ request.base_url }}?_view={{ v }}">{{ v }}</a></td>
+                    <td>
+                    {% for f in vals['formats'] %}
+                        <a href="{{ request.base_url }}?_view={{ v }}&_format={{ f }}">{{ f }}</a>
+                        {% if loop.index != vals['formats']|length %}<br />{% endif %}
+                    {% endfor %}
+                    </td>
+                    <td>{{ vals['namespace'] }}</td>
+                    <td>{{ vals['comment'] }}</td>
+                </tr>
+        {% endfor %}
+        </table>
+    {% endblock %}
+
+The alternates view template is shared for both a Register's alternates view as well as a class instance item's alternates view. In any case, since a :class:`.RegisterRenderer` class and a :ref:`example-renderer-reference` class both inherit from the base class :class:`.Renderer`, then they can both easily render the alternates view by calling the base class' :func:`pyldapi.Renderer.render_alternates_view` method. One distinct difference is that pyLDAPI will handle the alternates view automatically for a :class:`.RegisterRenderer` whereas a :ref:`example-renderer-reference` will have to explicitly call the :func:`pyldapi.Renderer.render_alternates_view`.
+
+Example usage for a :ref:`example-renderer-reference`:
+
+.. code-block:: python
+    :linenos:
+    :emphasize-lines: 7
+
+    # context: inside a 'custom' Renderer class which inherits from pyldapi.Renderer
+
+    # this is an implementation of the abstract render() of the base class Renderer
+    def render(self):
+        # ...
+        if self.view == 'alternates':
+            return self.render_alternates_view() # render the alternates view for this class instance
+        # ...

docs/source/class_item_template.rst

@@ -0,0 +1,41 @@
+Class template
+==============
+
+Example of a class item template customised for the `mediatypes dataset`_:
+
+.. _mediatypes dataset: https://github.com/nicholascar/mediatypes-dataset
+
+.. code-block:: HTML
+
+    {% extends "layout.html" %}
+
+        {% block content %}
+        <h1>{{ mediatype }}</h1>
+        <h3><a href="{{ request.values.get('uri') }}">{{ request.values.get('uri') }}</a></h3>
+        <h4>Source:</h4>
+        <ul>
+            <li><a href="https://www.iana.org/assignments/media-types/{{ mediatype }}">https://www.iana.org/assignments/media-types/{{ mediatype }}</a></li>
+        </ul>
+        {% if deets['contributors'] is not none %}
+        <h4>Contributors:</h4>
+        <ul>
+        {% for contributor in deets['contributors'] %}
+            <li><a href="{{ contributor }}">{{ contributor }}</a></li>
+        {% endfor %}
+        </ul>
+        {% endif %}
+        <h3>Other profiles, formats and languages:</h3>
+        <ul><li><a href="{{ request.base_url }}?uri={{ request.values.get('uri') }}&_view=alternates">Alternate Views</a></li></ul>
+    {% endblock %}
+
+Variables used by the class instance template:
+
+This will be called within a custom Renderer class' :func:`render`. See :ref:`example-renderer-reference`.
+
+.. code-block:: python
+
+    return render_template(
+        'mediatype-en.html',    # the class item template
+        deets=deets,            # a python dict containing keys *label* and *contributors* to its respective values.
+        mediatype=mediatype     # the mediatype class instance item name
+    )