-
Notifications
You must be signed in to change notification settings - Fork 42
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
raoashish10
wants to merge
6
commits into
HTTP-APIs:develop
Choose a base branch
from
raoashish10:develop
base: develop
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
731b57f
Added sphinx documentation
raoashish10 5501fb6
Corrected syntax
raoashish10 2f92dab
Added steps to run docs locally
raoashish10 4c3e1a4
Update README.md
raoashish10 cdf6ddc
Fixed and added new examples
raoashish10 ad42640
Added requirements and made changes to files
raoashish10 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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> | ||
i) Install requirements (It is *recommended* to use a virtual environment)<br> | ||
In the hydra-python-agent folder:<br> | ||
```pip install -r requirements.txt```<br> | ||
ii) Install hydra-python-agent<br> | ||
In the hydra-python-agent folder:<br> | ||
```python setup.py install```<br><br> | ||
2. Build the docs<br> | ||
```cd docs```<br> | ||
```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> | ||
```make clean```<br> | ||
```sphinx-build -b html ./source/ ./build/html/``` | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
agent | ||
============================================= | ||
|
||
.. automodule:: hydra_agent.agent | ||
:members: | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
collection_paginator | ||
============================================= | ||
.. automodule:: hydra_agent.collection_paginator | ||
:members: | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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'] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
helpers | ||
============================================= | ||
|
||
.. automodule:: hydra_agent.helpers | ||
:members: | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
querying_mechanism | ||
============================================= | ||
|
||
.. automodule:: hydra_agent.querying_mechanism | ||
:members: | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.