Docs

This is for all the documentation.

@flavio.tarsetti please see if the development installation guide fixes whatever issues you had!

Also please let me know of anything I should be adding to the dev guide.

• Check to make sure the docs works with beat/docs

changed the description

Right now there's just the installation & dev guide but the user docs are coming

added 3 commits

• 176aa73a - [docs] added line to install pyyaml to base conda env, #123 (closed)
• 276893f3 - [docs] added user guide via tutorial from slides
• 78e98968 - [docs] add editor breakdowns, #123 (closed)

Compare with previous version

@flavio.tarsetti could you check this out?

Also please check if this works with beat/docs since I don't know how that works!

Note: There are some generic~fuzzy things in the docs now because stuff is going to be changing over the next few months, especially in the editors.

@jdiefenbaugh I will check this out and let you know

For beat/docs, you can clone the public package git@gitlab.idiap.ch:beat/docs.git

Then change (or not) the version line in before_build.sh script:

if [[ $pkg  == "beat.editor" ]]; then
  version=docs
fi

Right now I added docs (as your branch you are working on is named docs, soon of course it will generate the documentation from master)

Then run the following:

./before_build.sh
../bob.admin/conda/conda-build.sh --python=3 conda

Where ./before_build.sh will download all the packages in a doc/ folder and ../bob.admin/conda/conda-build.sh --python=3 conda will generate the sphinx/ folder with all the documentation.

This way you will be able to check if the documentation you generated is fine before pushing a commit.

The user doc works only for the conda install of the package right? In devel mode it doesn't work.

Could you also clarify to me (and also in the docs maybe) why we need the /bin/beateditor --dev to run this flask server ?

I mean the complete beat.editor will actually work with npm start for the webpack dev server, so why two servers with flask needed here?

added 1 commit

• 26ea862a - [docs] fix typo

Compare with previous version

You need /bin/beateditor --dev because the --dev flag prevents the server from serving the distributable (prod) HTML/JS/CSS files. Since the HTML/JS/CSS will be served by the webpack dev server, you only need the REST API from the python server.

The webpack dev server only serves the website stuff, not the API.

resolved all discussions

But again why do we need beat.web REST API here ?

I'm a bit confused but I guess the answer to this question is maybe here:

https://gitlab.idiap.ch/beat/beat.editor/blob/docs/doc/api.rst#L7

But the doc is empty for this part.

Oh it's not the beat.web REST API, it's the beat.editor REST API. beat.editor has a small Python server (using Flask) to let the website operate on the prefix (getting stuff via GET, making stuff via POST, changing stuff via PUT, deleting stuff via DELETE).

@flavio.tarsetti anything else I need to change/etc.?

Thanks for the doc. It's good as it's really some kind of tutorial for the user guide, and it's very nice. Looks good to me.

Could you add the API documentation too as it's empty now.

It would be good to add some more stuff for the Development part in the JS stuff where you can describe a little more each modules as it's a bit light for now.

I think a good thing would be to start keeping all this up-to-date with the new modifications you are working on from now on. Maybe some kind of sphinx-js would be good too to keep the code documented as it's not documented for now.

Does this seem good ?

API Documentation

As far as the API docs go, shouldn't I actually be removing the API page completely? Correct me if I'm wrong, but the API documentation is only for packages providing an library/API for consumers. Since our package is purely an end-user app and so doesn't provide any library/API interface, shouldn't there not be an API page?

Dev docs

Sure I'll expand on that stuff, probably a good idea.

Sphinx-JS-like-thing

I wish there was a tool like Sphinx for modern JS :(. Unfortunately there's not yet. There's stuff like JSDoc, which is fine for oldschool JS but won't work for contemporary JS projects. There's also stuff like Storybook, which is super cool but not stable enough. I actually spent alot of time with both of these last year when I started this project, but either projects are abandoned, not mature~stable enough, or only support old JS. In awhile Storybook might end up being our best bet.

Keeping up-to-date

Yes agreed! It would be best to review the docs before an MR merge.