http-apis / http-apis.github.io

HydraEcoSystem.Org - Main documentation entrypoint for Hydra Ecosystem's tools.

Hydra Ecosystem Documentation

This is the source-code behind hydraecosystem.org, the official documentation of the Hydra Ecosystem toolset.

Viewing the Documentation Offline

The documentation is hosted on GitHub Pages and uses the static site generator named Jekyll. You may see this video to get started with jekyll. If you want to see what your modifications to the documentation would look like, before you make a PR, please run the following commands:

• Check if you have Jekyll installed. if not, follow the installation guide

jekyll -v

• Start a live-server which serves statically generated content, changes made will make real-time changes to it.

jekyll serve --incremental

Note: Just running the jekyll command without any arguments, might build a static website in html form with-in the public directory, please make sure not to include this in your PR.

Contributing

The Hydra Ecosystem is an Open Soure project and we have our source code licensed under the permissible MIT license, please make any contribution to the project by opening an issue and a subsequent PR to solve the same.

http-apis.github.io's Issues

Add GSoD on main page footnote

Add GSoD participation with GSoC in the footnote at https://www.hydraecosystem.org/

I should do this soon

Add a twitter widget to the main page

we should be displaying our twitter account on the main page https://twitter.com/HydraEcosystem

Warnings on `jekyll seve`

The initiation of the web-server outputs a few warnings in the CLI. These are

Deprecation: You appear to have pagination turned on, but you haven't included the `jekyll-paginate` gem. Ensure you have `gems: [jekyll-paginate]` in your configuration file.

and

Deprecation: The 'plugins' configuration option has been renamed to 'plugins_dir'. Please update your config file accordingly.

Proper Indexing in the documentation

Since documentation can contain many sub-sections, sometimes it's difficult to share some specific section. It can be resolved by ensuring proper indexing of all the sub-sections. This can make navigating around or sharing the documentation easier.

For eg: To reach setting up the GUI section of the in this page, we have to scroll to it. It will be nice to have urls of sub sections like these: https://www.hydraecosystem.org/Design#dataflow (To reach to the data-flow section of the page) in all the pages.

Complete the missing paragraphs in Hydra-agent

Last two paragraphs are missing.

https://github.com/HTTP-APIs/http-apis.github.io/blob/master/hydra-agent-redis-graph.md

"get_classes" method in doc_parse.py dose not take python dictonary as argument.

In the Usage page of the Documentation (http://www.hydraecosystem.org/01-Usage) the "get_classes" method contains python dictionary as an argument doc_parse.get_classes(apidoc.generate()) But the get_class method requires the HydraDoc object as argument.

Update documentation with respect to the changes done in Agent

Hydra Python Core Documentation

Currently, at hydra core we have very little usage documentation on how to interact with the Hydra Doc. Also, we have almost no references to it around the documentation as we checked in #18 and it's a quite important repository.

It would be good to have a more detailed on basics of how to interact with the apidoc and other important info, this is a good task for beginners becoming familiar with the Hydra Spec.

Considering UI changes

The documentation is maintained in a manner that is un-structured. Building a UI that helps structure the documentation as well as using a better generator for the same can help make the experience of both the writer as well as the reader/end-user better or more streamlined.

Examples of structured documentation UIs include:

• https://www.tensorflow.org/guide/
• https://svelte.dev/docs

Mentor mail IDs should be present on project idea page.

Mentor mail IDs Should be added at the end of the project idea page gsoc-22.

Write an article about Hydra usage for OS maps

This API publishes OpenStreetMap tiles using Hydra: https://tiles.openplanner.team/planet/14/8411/5485/

It would be good to have a page in the docs or an article explaining this implementation.

In particular check usage at:

"hydra:search":{
  "@type":"hydra:IriTemplate",
  "hydra:template":"https://tiles.openplanner.team/planet/14/{x}/{y}",
  "hydra:variableRepresentation":"hydra:BasicRepresentation",
  "hydra:mapping":[{
    "@type":"hydra:IriTemplateMapping",
    "hydra:variable":"x",
    "hydra:property":"tiles:longitudeTile",
    "hydra:required":true
    },{
    "@type":"hydra:IriTemplateMapping",
    "hydra:variable":"y",
    "hydra:property":"tiles:latitudeTile",
    "hydra:required":true}]}}

[UPDATE]
We have already a document page that describes this, but we may want to have an article that demos the usage of navigating the API and explains why Hydra is useful for that.

Create a page that explains the IriTemplate starting from an example

Starting from the triples example in HydraCG/Specifications#171

That has been ported in JSON-LD by @vddesai1998 as:

{
    "@context": "/serverapi/context.jsonld",
    "@id": "https://tiles.openplanner.team/planet",
    "@type": "Collection",
    "search": {
        "@type": "IriTemplate",
        "template": "https://c.tile.openstreetmap.org/{z}/{x}/{y}.examplejsonld",
        "variableRepresentation": "BasicRepresentation",
        "mapping": [
            {
                "@type": "IriTemplateMapping",
                "variable": "x",
                "property": "tiles:longitudeTile",
                "required": true
            },
              {
                "@type": "IriTemplateMapping",
                "variable": "y",
                "property": "tiles:latitudeTile",
                "required": true
            },
              {
                "@type": "IriTemplateMapping",
                "variable": "z",
                "property": "tiles:zoomTile",
                "required": true
            }
        ]
    }
}

Produce a documentation section that explains:

• which problem is solved (uniquely identify a tile on a map by indication of row, height and zoom)
• how the variables in the IRI (z/x/y) are mapped to a templates
• what is VariableRepresentation
• ...

Update documentation with respect to changes in core and hydrus

A lot of new changes in hydra-python-core and the hydrus server have not been incorporated in the docs yet. This really confuses a new user when he is going through the docs like developing with hydrus.

Some of the major changes required immediately that I can think from the back of my mind are:

• read-only and write-only properties are now readable and writeable. (Read here)
• Status Codes now can't be defined in python dict objects. They need to be defined using either HydraStatus or HydraError classes. (related to here)

I will keep appending more changes required to this issue.

Additions to Starting-Material.md

In the Starting-Material.md, it would be super helpful if Linked Data and JSON-LD were added before specifications. The https://www.hydra-cg.com/spec/latest/core/ require an understanding of these concepts.

Double-check and modify references to parser and core

Now that the parser and core have been moved to their own repository, documentation has to point to the new repos:

• https://github.com/HTTP-APIs/hydra-openapi-parser/issues
• https://github.com/HTTP-APIs/hydra-python-core/issues

Add github ribbon to homepage

Mobile view, overflow

There is a content overflow issue when looking at the website in mobile view.

And

Display the same.

Parser page found not found

The page under https://www.hydraecosystem.org/Parser is returning not found instead of returning the content at https://github.com/HTTP-APIs/http-apis.github.io/blob/master/pages/Parser.md

"add_supported_class" method in doc_writer.py dose not take collection as argument.

In the Usage page of the Documentation (http://www.hydraecosystem.org/01-Usage) the "add_supported_class" method contains two arguments apidoc.add_supported_class(class_, collection=True) where as in the doc_writer.py there in no such collection agrument required.

Page fragments are not working

If I try to navigate to the page title: https://www.hydraecosystem.org/gsoc-19#Ideas

the browser does not reach the right "Ideas" paragraph in the page

Fix website pages #tags

If trying to link to a tag in the URL in the website like https://www.hydraecosystem.org/00-Home#what-makes-the-difference the result is that the title and upper part of the paragraph got hidden underneath the header.

Twitter widget size

I think the Twitter widget on the main page is too big, compared to the other content on the page. It looks a bit distracting.

It might look more visually pleasing if it was smaller and maybe more to the side rather than centered and huge like it is right now. Something similar to this:

Add Gitter icon/ribbon to the homepage

Hydra Eco Demo - [Discussion]

Hello guys,

So I've been trying to architect a straightforward but complete demo that enables people to quickly try Hydra Eco's tools and get the feel of Hydra/Semantics/Linked Data. This is what I came up considering our time frame:

(Click to expand)

1. This is the API Graphical representation. It has three already deployed -similar but slightly different- hydrus APIs that the user can select as the target. The goal is to show how decoupled/constant the Agent can be even with different APIs.

2. This is where the user can interact. Since we want the user to easily interact without much semantics knowledge, this is a dynamic interface(built according to the apidoc) for the Agent. It has buttons for the critical parts so the user can always send some request and see what happens. The red buttons are the selected ones, and a valid combination will always be selected. The goal here is for the user to feel that a hypermedia API will give the Agent enough information to automatically structure all kinds of requests possible and create a descriptive environment .

3. This is where the user can insert data/filter and write more detailed interactions, instead of only fetching the whole collection. Here the user can also use the new search functionalities and query for linked data. For example, he can filter a drone by the battery of it's State DroneState[Battery]. The goal here is for the user to feel the advantages of Linked data + Hydra.

Important Obs.:

• This mockup is mostly to discuss functionality. Since I think there's a decent likelihood we use Flask to maintain the whole demo in Python(also up for discussion), it will look different.
• The graph on the left won't be dynamic, at least at first, or else it will take too long. I'm thinking about three different static SVGs.
• Mobile responsiveness won't be an initial concern.