added some stuff to adapters.md and minor formatting edits #17
Conversation
A1Liu
changed the title
|
the minor formatting edits are basically all just changing links so that they use variables instead of inline links in the middle of the text body. |
There was a problem hiding this comment.
Thanks so much for the PR! This is a very important part of the documentation and I appreciate you getting a head start with this.
However, I don't know if the yaml adapter is the best example for the reasons listed in the comments. I think we should think more about what the best example would be.
Overall, I think this should read more like a tutorial for creating an adapter, rather than an explanation of some existing code. I think it would be easier to read and more useful. IMO we should come up with a new example for a "toy" adapter, or set of adapters, that ingest data from the web, and take the reader through building it piece by piece. We could also use one of the existing RPI adapters that pull real data, but it should still read more like a tutorial than a README.
| <!-- TODO: Make diagram --><!-- | ||
|
|
||
| - -> | ||
| When Yacs needs information that isn't stored in its database, it sends an HTTP request to the adapter that is responsible for that information. Then that adapter works its magic, and sends the information back in JSON format. This document is going to focus on the [`yaml-rpi`][yaml-rpi-adapter] adapter and use its code in examples. The document `app.rb` will also be edited for clarity to this: |
There was a problem hiding this comment.
This isn't technically correct. Every adapter is polled on a fixed interval, and Yacs saves the combined result/
| @@ -68,17 +94,49 @@ The JSON API is based off of JavaScript Object Notation: | |||
|
|
|||
| ``` | |||
|
|
|||
| Notice that objects are surrounded by `{curly brackets}`, and both attributes and values are surrounded by `"double quotes"`. Each attribute-value pair is specified by a single line, with a colon separating attributes and values, and attribute-value pairs are separated by a comma. Note that spacing is irrelevant to the formatting of the document except in strings -- anything between double quotes must be on a single line. | |||
| Objects are surrounded by `{curly brackets}`, and both attributes and values are surrounded by `"double quotes"`. Each attribute-value pair is specified by a single line, with a colon separating attributes and values, and attribute-value pairs are separated by a comma. Spacing is irrelevant to the formatting of the document except in strings -- anything between double quotes must be on a single line. Finally, there is no syntax for making comments. | |||
There was a problem hiding this comment.
I don't think it's within the scope of this documentation to explain how JSON works. I'd rather just provide a link as a reference.
|
|
||
| In the `yaml-rpi` adapter, this is done through | ||
| require 'sinatra/json' |
There was a problem hiding this comment.
While helpful for understanding this particular adapter's code, I think including such specific information about ruby distracts the reader from what is important. If I'm new to this project and want to write an adapter, I probably won't use ruby if I don't already know it.
|
|
||
|
|
||
| ## HTTP Protocol | ||
|
|
||
| <!-- IDK what to do here, I don't really understand this part fully yet |
There was a problem hiding this comment.
This is just setting up the web server, and is very specific to Sinatra, the web framework we use in most of the adapters.
| @@ -14,7 +14,7 @@ This is a good place to start if you don't know where something lives, or want t | |||
| The above diagram shows how each of the services connect. | |||
| For more in-depth information on how Yacs operates as a whole, see [overview](architecture/overview) | |||
|
|
|||
| ### [core](https://github.com/yacs-rcos/yacs/blob/master/core) | |||
There was a problem hiding this comment.
I think all of these changes are in your other PR, can we remove them from here and vice versa?
There was a problem hiding this comment.
I'll open another PR with just adapter.md changes
|
|
||
| ## Data Source | ||
| The first thing your adapter needs is a place to get data from. In the `yaml-rpi` adapter, that place is a file called `schools-and-subjects.yml`. | ||
| The first thing your adapter needs is a place to get data from. In the `yaml-rpi` adapter, that place is a file called `schools-and-subjects.yml`: |
There was a problem hiding this comment.
I don't know if this is the best example to start with. It is the simplest, but it is also the least useful. It is not typical that data will be coming from a config file, and I don't necessarily want to encourage people to use adapters that way. Although they can be used like this, they are intended to ingest dynamic data from some other source on the web.
There was a problem hiding this comment.
Hmmm, do you think this markdown should use a script in another language? There's quite a few ruby/sinatra specific parts for the adapters as far as I can tell. Maybe it'd be better to use python or pseudo-code in the toy example code?
There was a problem hiding this comment.
Possibly, I don't think ruby is a bad choice here, we just need to find the right format for this guide.
|
Closing this as it has been superseded by #22 |
Added app.rb examples from yaml-rpi. Will try to write explanations once I understand the ruby syntax and sinatra stuff better