Documentation/rest api web #2770

dmoisej · 2019-06-10T16:51:58Z

Basics

Check relevant points but please do not remove entries.
Do not describe the purpose of this PR in the PR description but:

Short descriptions should be in the release notes (added as entry in
doc/news/_preparation_next_release.md which contains _(my name)_)
Please always add something to the the release notes.
Longer descriptions should be in documentation or in design decisions.
Describe details of how you changed the code in commit messages
(first line should have module: short statement syntax)
References to issues, e.g. close #X, should be in the commit messages.

Checklist

Check relevant points but please do not remove entries.
For docu fixes, spell checking, and similar none of these points below
need to be checked.

I added unit tests
I ran all tests locally and everything went fine
affected documentation is fixed
I added code comments, logging, and assertions (see Coding Guidelines)
meta data is updated (e.g. README.md of plugins and METADATA.ini)

Review

Reviewers will usually check the following:

Code is conforming to our Coding Guidelines
APIs are conforming to our Design Guidelines
Code is consistent to our Design Decisions
Documentation is concise and good to read
Examples are well chosen and understandable

Labels

Add the "work in progress" label if you do not want the PR to be reviewed yet.
Add the "ready to merge" label if the build server is happy and also you
say that everything is ready to be merged.

@markus2330 @sanssecours please review my pull request

dmoisej · 2019-06-10T16:55:54Z

@markus2330 @sanssecours the pull request is related to the #2746

It is just another copy as I was forced to refork the repository. The reason for that was, that I mistakenly added commits to the master, which are not merged into this (main) repository, so I get those changes on every pull request.

Deleting commits with the git rebases didn't help me. Additionally I had some problems with jenkins tool, which checks, if the commit can be merged or not.

markus2330

Thank you for the improved tutorial

markus2330 · 2019-06-10T17:03:02Z

src/tools/web/README.md

+  - `cd libelektra/src/tools/web`
+  - `cd elektrad`
+  - `npm install`
+  - `npm start` (replaces `kdb run-elektrad`)


What means "replaces" here? From source you use npm start, if installed kdb run-elektrad. It seems to be that this instructions duplicate the instructions above or web/elektrad?

Actually, I just copy pasted what is written in https://www.libelektra.org/tools/web in the section "Running from source".

It means, that all 4 commands:

cd libelektra/src/tools/web

cd elektrad

npm install

npm start

replace kdb run-elektrad

Actually, I just copy pasted

Please don't do this.

https://www.libelektra.org/tools/web is generated from this document.

markus2330 · 2019-06-10T17:04:30Z

src/tools/web/README.md

+  - `npm start` (replaces `kdb run-elektrad`)
+
+- by installing elektrad tool together with Elektra and run it
+  - please see the documentation [here](https://www.libelektra.org/tools/web) on how to install and run the elektra-web tool


Is this self-reference on purpose?

oh sorry, I didn't notice that, I will improve this

markus2330 · 2019-06-10T17:05:16Z

src/tools/web/README.md

+Let's create the new key-value pair `user/test`:
+
+```sh
+kdb set user/test 5


How to set via REST API?

markus2330 · 2019-06-10T17:06:14Z

src/tools/web/README.md

+    "value": "5",
+    "meta": ""
+}
+```


Please refer to the API docu for this.

Will improve

Not yet done?

@markus2330 it is done. In the file I showed, how the user can set a value via curl

dmoisej · 2019-06-10T20:39:41Z

@markus2330, I updated the guide, please check

markus2330 · 2019-06-10T20:43:34Z

The installation procedure is still copy&pasted?

dmoisej · 2019-06-10T21:26:49Z

@markus2330 , no, the installation of the web-elektrad tool is not copy pasted. Right now, I just added the note, "please see the section Building with elektra-web Tool".

The only thing, which is copy pasted, is four commands to start the server manually:
cd libelektra/src/tools/web
cd elektrad
npm install
npm start

But everything others is written newly.

sanssecours · 2019-06-11T08:58:54Z

It is just another copy as I was forced to refork the repository. The reason for that was, that I mistakenly added commits to the master, which are not merged into this (main) repository, so I get those changes on every pull request.

You can always just create another branch based on the master branch (or any other branch) of this repository. Usually you do not need to

create a new fork of a repository you already cloned, or
create a new PR (just rebase and force-push your changes)

. Anyway, I would recommend you read the book “Git Pro” to learn a little bit more about the versioning tool. I also recommend you use a GUI, which usually simplifies working with git quite a lot. If you have a Mac (or use Windows), then I recommend you use Fork. Tower is even better in my experience, but is quite expensive and uses a really user-unfriendly licensing model.

dmoisej · 2019-06-11T09:05:18Z

@sanssecours, thank you for your recommendation. I didn't know, that I could create the new branch from master of the main repository as I haven't worked with forked repositories before. But I will take it into account right now. Sorry for inconveniences.

sanssecours

Thank you for incorporating the changes I suggested. Looks like the formatting check still fails. Can you please follow the steps suggested by the build server, or alternatively, format the ReadMe with prettier, as described here?

doc/news/_preparation_next_release.md

src/tools/web/README.md

dmoisej · 2019-06-11T09:56:04Z

@sanssecours I will try to fix code formatting later today.

kodebach

Apart from the stuff that @markus2330 already requested, this looks good to me.

dmoisej · 2019-06-12T11:59:26Z

@sanssecours , @markus2330 I was forced to change the output format from json to sh because in the doc/CODING.md, on the line 376, it is specified:

README.md and tutorials should be written exclusively with shell recorder syntax so that we know that the code in the tutorial produces output as expected

I checked then README.md with prettier tool after the changes and everything works well right now.

Additionally to this, I tried to reformat the README.md file together with scripts/reformat-markdown script from the libelektra project root.
After running:

sh scripts/reformat-markdown src/tools/web/README.md

I've got the error:

scripts/reformat-markdown: Zeile 7: $'\r': Kommando nicht gefunden.

sanssecours · 2019-06-12T12:33:01Z

@sanssecours , @markus2330 I was forced to change the output format from json to sh because in the doc/CODING.md, on the line 376, it is specified:

README.md and tutorials should be written exclusively with shell recorder syntax so that we know that the code in the tutorial produces output as expected

Please do not use incorrect language specifiers. The code block in question contains JSON code, not code for the Bourne shell (aka sh). The language specifier should reflect this.

You do not need to write this tutorial using (Markdown) Shell Recorder syntax, even if the sentence you quoted might suggest otherwise.

After running:

sh scripts/reformat-markdown src/tools/web/README.md

I've got the error:

scripts/reformat-markdown: Zeile 7: $'\r': Kommando nicht gefunden.

Interesting. Did you maybe change the line endings of reformat-markdown from Unix (\n) to DOS line endings (\r\n)?

dmoisej · 2019-06-12T12:44:32Z

@sanssecours ,

Please do not use incorrect language specifiers. The code block in question contains JSON code, not code for the Bourne shell (aka sh). The language specifier should reflect this.

You do not need to write this tutorial using (Markdown) Shell Recorder syntax, even if the sentence you quoted might suggest otherwise.

Okay but if the build is failed because I specify any other language, then sh, so what should I do right now? Should I change something? If yes, than what exactly should I change and on what? Or will my pull request will be merged?

Interesting. Did you maybe change the line endings of reformat-markdown from Unix (\n) to DOS line endings (\r\n)?

I tried it quickly form my other laptop, where I have windows installed. In the evening I will try to execute this script on other laptop, where I have linux installed.

sanssecours · 2019-06-12T12:58:13Z

If yes, than what exactly should I change and on what?

I just pushed a commit that contains my suggested changes.

Or will my pull request will be merged?

I think as soon as Markus and the build server are happy with the status of the PR, Markus will merge your updates.

dmoisej · 2019-06-12T13:21:33Z

@sanssecours thank you very much for help.

markus2330 · 2019-06-12T19:11:44Z

Thank you!

dmoisej added 2 commits June 10, 2019 18:47

Add description on how to test REST-API on localhost

401f26e

Add release notes

e7f167c

dmoisej mentioned this pull request Jun 10, 2019

Add example how to test rest api on localhost #2746

Closed

9 tasks

Add fix to the release ntoes

dea37cc

markus2330 suggested changes Jun 10, 2019

View reviewed changes

Update the guide

7a58bcd

markus2330 requested a review from kodebach June 10, 2019 20:43

Fix typo

1c11f59

sanssecours reviewed Jun 11, 2019

View reviewed changes

sanssecours added cm2019s enhancement usability labels Jun 11, 2019

kodebach reviewed Jun 11, 2019

View reviewed changes

Fix formatting

fa1782b

dmoisej force-pushed the documentation/rest-api-web branch from f1f2f21 to fa1782b Compare June 11, 2019 22:33

Moiseiuk added 2 commits June 12, 2019 09:33

Update doc again

b8786cb

Fix README.md formatting

2ba6e7b

Documentation: Fix language identifier

06cae45

markus2330 approved these changes Jun 12, 2019

View reviewed changes

markus2330 merged commit ea418f1 into ElektraInitiative:master Jun 12, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation/rest api web #2770

Documentation/rest api web #2770

dmoisej commented Jun 10, 2019 •

edited

Loading

dmoisej commented Jun 10, 2019

markus2330 left a comment

markus2330 Jun 10, 2019

dmoisej Jun 10, 2019

markus2330 Jun 10, 2019

markus2330 Jun 10, 2019

dmoisej Jun 10, 2019

markus2330 Jun 10, 2019

markus2330 Jun 10, 2019

dmoisej Jun 10, 2019

markus2330 Jun 12, 2019

dmoisej Jun 12, 2019 •

edited

Loading

dmoisej commented Jun 10, 2019

markus2330 commented Jun 10, 2019

dmoisej commented Jun 10, 2019

sanssecours commented Jun 11, 2019

dmoisej commented Jun 11, 2019 •

edited

Loading

sanssecours left a comment

dmoisej commented Jun 11, 2019

kodebach left a comment

dmoisej commented Jun 12, 2019

sanssecours commented Jun 12, 2019

dmoisej commented Jun 12, 2019

sanssecours commented Jun 12, 2019

dmoisej commented Jun 12, 2019

markus2330 commented Jun 12, 2019

Documentation/rest api web #2770

Documentation/rest api web #2770

Conversation

dmoisej commented Jun 10, 2019 • edited Loading

Basics

Checklist

Review

Labels

dmoisej commented Jun 10, 2019

markus2330 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmoisej Jun 12, 2019 • edited Loading

Choose a reason for hiding this comment

dmoisej commented Jun 10, 2019

markus2330 commented Jun 10, 2019

dmoisej commented Jun 10, 2019

sanssecours commented Jun 11, 2019

dmoisej commented Jun 11, 2019 • edited Loading

sanssecours left a comment

Choose a reason for hiding this comment

dmoisej commented Jun 11, 2019

kodebach left a comment

Choose a reason for hiding this comment

dmoisej commented Jun 12, 2019

sanssecours commented Jun 12, 2019

dmoisej commented Jun 12, 2019

sanssecours commented Jun 12, 2019

dmoisej commented Jun 12, 2019

markus2330 commented Jun 12, 2019

dmoisej commented Jun 10, 2019 •

edited

Loading

dmoisej Jun 12, 2019 •

edited

Loading

dmoisej commented Jun 11, 2019 •

edited

Loading