Skip to content

Added sphinx documentation #163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
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)
18 changes: 18 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# How to run the docs locally

1. <b>(Skip this step if you have already installed hydra-python-agent)</b> <br>
&nbsp;i) Install requirements (It is *recommended* to use a virtual environment)<br>
&nbsp;In the hydra-python-agent folder:<br>
&nbsp;```pip install -r requirements.txt```<br>
&nbsp;ii) Install hydra-python-agent<br>
&nbsp;In the hydra-python-agent folder:<br>
&nbsp;```python setup.py install```<br><br>
2. Build the docs<br>
&nbsp;```cd docs```<br>
&nbsp;```sphinx-build -b html ./source/ ./build/html/```<br>
HTML files are generated in the build/html folder which can be used to check the pages.
<br><br>
<b>In order to make a clean build:</b><br>
&nbsp;```make clean```<br>
&nbsp;```sphinx-build -b html ./source/ ./build/html/```

35 changes: 35 additions & 0 deletions docs/make.bat
Original file line number Diff line number Diff line change
@@ -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% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd
6 changes: 6 additions & 0 deletions docs/source/agent.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
agent
=============================================

.. automodule:: hydra_agent.agent
:members:

5 changes: 5 additions & 0 deletions docs/source/collection_paginator.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
collection_paginator
=============================================
.. automodule:: hydra_agent.collection_paginator
:members:

55 changes: 55 additions & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))


# -- Project information -----------------------------------------------------

project = 'hydra-python-agent'
copyright = '2021, Hydra Ecosystem'
author = 'Hydra Ecosystem'

# The full version, including alpha/beta/rc tags
release = '0.0.1'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc','sphinx.ext.coverage',
'sphinx.ext.napoleon']

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
6 changes: 6 additions & 0 deletions docs/source/helpers.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
helpers
=============================================

.. automodule:: hydra_agent.helpers
:members:

205 changes: 205 additions & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
.. hydra-python-agent documentation master file, created by
sphinx-quickstart on Mon Feb 1 16:42:29 2021.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to hydra-python-agent's documentation!
==============================================

hydra-python-agent is a `smart Hydra client <http://www.hydra-cg.com/>`__ implemented in
Python which works with hydrus. Reference implementation is
`Heracles.ts <https://github.com/HydraCG/Heracles.ts>`__. Smart clients are generic automated clients
that establish resilient connected data networks leveraging
knowledge graphs.

agent module
------------
The agent is used in order to:
1. Provide a seamless Client that can be used to communicate with Hydra APIs.
2. Cache metadata from the Hydra server it connects to, to allow querying on the client-side.
3. Maintain a syncrhonization mechanism which makes sure cached resources are consistent.
4. The graph can be queried using OpenCypher.

The agent module contains a main Agent class. The agent module uses a redis caching layer to store
the generated apidoc and allow efficient querying.
This class inherits classes from the socketio module and the Session class from the requests module.
This class is first initialized with the main entrypoint url.
(Example) In this case, the entrypoint_url is "http://localhost:8080/serverapi".
A connection to the redis server is initialized using the redis modules (present in the redis_core files)
and a connection with the hydrus server is established at the entrypoint url provided using socketio.

The Agent class has various functions. Some commonly used functions are explained below:

1) fetch_apidoc()
This function is used to generate the apidoc for the entrypoint_url initialized and the name of the api
which is extracted from the entrypoint_url. This apidoc is generated by passing the apidoc present in hydrus
through the doc_maker module from hydra-python-core.
2) get()
This function is used to handle a GET request to the url mentioned as a parameter. The function returns an apidoc
for the respective resource from the redis graph in a JSON format.

3) post()
This function is used to handle a POST request to the url mentioned as a parameter. It is used to update the resource at the specified
url.

4) put()
This function is used to handle a PUT request to the url mentioned as a parameter. It is used to add a resource at the specified url.

The final goal is to create a Client that can connected to multiple hydrus servers and operate between them while caching information in
a graph-based database(Redis).
This should enable the client to have an "aggregated view" of the connected network (the network of all the servers it connects to) and
make complex sematic queries to it.

Usage
-----

For the installation process, click `here <https://github.com/HTTP-APIs/hydra-python-agent#installation>`__

1. Initializing the Agent:

.. code-block:: python

from hydra_agent.agent import Agent
agent = Agent("http://localhost:8080/serverapi")

2. To add a new resource using a *PUT* request:

Syntax:

.. code-block:: python

agent.put("http://localhost:8080/serverapi/<ResourceType>,<new_property>")

Example:

.. code-block:: python

new_resource={
"@type" : "Movie",
"movie_name" : "The Shining",
"movie_director" : "Stanley Kubrick"
}
agent.put("http://localhost:8080/serverapi/Movie/", new_resource)

Example output:

.. code-block:: python

({'@context': 'http://www.w3.org/ns/hydra/context.jsonld', '@type': 'Status', 'description': 'Object with ID 9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed successfully added', 'statusCode': 201, 'title': 'Object successfully added'}, 'http://localhost:8080/serverapi/Movie/9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed')

3. To add new members to a collection:

Syntax:

.. code-block:: python

request_body = {
"@type": "<CollectionType>",
"members": [
{
"@id": "<ResourceID>",
"@type": "<ResourceType>"
},
{
"@id": "<ResourceID>",
"@type": "<ResourceType>"
},
]
}
agent.put("http://localhost:8080/serverapi/<CollectionType>", request_body)

Example:

.. code-block:: python

request_body = {"@type" : "MovieCollection","members": [{"@id" : "9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed","@type" : "Movie"},]}
agent.put("http://localhost:8080/serverapi/MovieCollection", request_body)

Example output:

.. code-block:: python

({'@context': 'http://www.w3.org/ns/hydra/context.jsonld', '@type': 'Status', 'description': 'Object with ID 2d2bdaa9-8f9c-46fe-ac16-6d69b7e52bf3 successfully added', 'statusCode': 201, 'title': 'Object successfully added'}, 'http://localhost:8080/serverapi/MovieCollection/2d2bdaa9-8f9c-46fe-ac16-6d69b7e52bf3')

4. To *GET* a resource:

a) To get a collection, the syntax is

.. code-block:: python

agent.get("http://localhost:8080/serverapi/<CollectionType>/")

Example:

.. code-block:: python

agent.get("http://localhost:8080/serverapi/MovieCollection")

Output:
Returns the ApiDoc for the resource MovieCollection

b) To get members of a specific collection, the syntax is

.. code-block:: python

agent.get("http://localhost:8080/serverapi/<CollectionType>/<Collection-ID>")

Example:

.. code-block:: python

agent.get("http://localhost:8080/serverapi/MovieCollection/2d2bdaa9-8f9c-46fe-ac16-6d69b7e52bf3")

c) To get members of a specific resource, the syntax is

.. code-block:: python

agent.get("http://localhost:8080/serverapi/<ResourceType>/<Resource-ID>")

Example:

.. code-block:: python

agent.get("http://localhost:8080/serverapi/Movie/9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed")

Example output:

.. code-block:: python

{'@context': '/serverapi/contexts/Movie.jsonld', '@id': '/serverapi/Movie/9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed', '@type': 'Movie', 'movie_director': 'Stanley Kubrick', 'movie_name': 'The Shining'}

Note: Collection-IDs and Resource-IDs are present in the database file generated after running hydrus.

5. To update a resource using a *POST* request:

Syntax:

.. code-block:: python

agent.post("http://localhost:8080/serverapi/<ResourceType>/<Resource-ID>,<updated_property>")

Example:

.. code-block:: python

existing_resource["movie_name"] = "A Clockwork Orange"
agent.post("http://localhost:8080/serverapi/Movie/9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed", existing_resource)

.. toctree::
:maxdepth: 2
:caption: Contents:

agent
collection_paginator
helpers
querying_mechanism




Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
6 changes: 6 additions & 0 deletions docs/source/querying_mechanism.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
querying_mechanism
=============================================

.. automodule:: hydra_agent.querying_mechanism
:members:

2 changes: 2 additions & 0 deletions requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ requests
python-socketio
-e git+https://github.com/RedisGraph/redisgraph-py@d790e35b7017510c4baad85e3c572249a9ed7279#egg=redisgraph
-e git+https://github.com/http-apis/hydra-python-core@master#egg=hydra_python_core
Sphinx==3.1.2
sphinx-rtd-theme==0.5.1