SDK / Library for Angular 2

[tisto]

A few issues need to be discussed before we can start:

• Licensing (which License should we choose?)
• Scope (what is our library supposed to do, e.g. just a thin wrapper around plone.restapi/plone_server or a generic API for Plone the CMS?)
• Name (depends on scope)
• Repository (how do we avoid name collisions in the future?)
• Documentation (how do we document Angular 2 code?)

[ebrehault]

We do not want to start directly with a super layered architecture with dozens of packages.
We will start with 2 packages:

• @plone/restapi-angular
• @plone/resourceapi-angular

The resourceapi-angular package will only focus on wrapping the REST API calls dedicated to pure content management.
The restapi-angular package will use the resourceapi-angular package and will add:

• wrapping for all the other API calls (user management, registry, etc.)
• traversal: view traversing (like routing) but also context traversing (for example, ability to get the parent resource of the current one)
• JSON schema-based form generation
• layout editor (Mosaic-like)
• UI components (breadcrumb, navigation, toolbar, etc.)
• views (view, edit, sharing, etc.)

This package might be splitted later on smaller pieces.

[ebrehault]

Regarding documentation, we will use Markdown as it is the standard for JS packages.

Note: there is a markdown renderer for Sphinx, so it should work for docs.plone.org. @svx do you have any opinion on that?

[svx]

Keep in mind that the markdown support for sphinx is limited, because Commonmark doesn’t support a lot of the concepts that RST lets you represent.

There is no standardized way in Commonmark to represent inline or block levels constructs.
Things like the toctree directive and :ref: markup don’t have an analog.

Further, that also would mean, I have to write new and adjust current tests in order to use them against markdown, this is possible but will take some time.

What is the long term plan ? Should these docs be included into docs.plone.org at some point ?
If yes, we have to adjust/change more things, like style-guides, writing manuals and so on, markdown differs from reST :)

We do not want to confuse user who want to contribute to docs, right ? :)

Including them into our current build process is another issue, but this will hopefully solved with the currently work in process new test/build/and hosting setup.

[ebrehault]

@svx I know rst is much more powerful than md. What's for sure is we need at least an README.md file in our repository root or it will looks very bad on npmjs.org. Maybe we can keep rst, and generate README.md automatically from README.rst?

[svx]

@ebrehault are we talking about 'just' the README or about the docs in /docs, too ?

[ebrehault]

@svx about the entire docs in /docs (I just wanted to highlight the only technical constraint we have is README.md).

[svx]

OK.
Using pandoc to generate .md from .rst is not nice, it is kind of working but usually you have to fix stuff from hand, for sure if people do not write 100% proper reST.

If that is the only thing, meaning md is required for the README, what is with write the README in markdown and the docs in reST ?

Pro:

• You have more freedom because reST is more powerfull

Con:

• Could possible confusing for people.

That is btw, how I do it for some npm packages, for me this approach works, but that does not say it will work for you :).

[svx]

I will be more than happy to update our style-guide with a couple of lines and an example to explain that if you publish this package to npm, use markdown for your README.

:)

Just tell me for which version 5.1 ? 6 ?

[datakurre]

👍 for README in MD, long docs in ReST

Including a local Sphinx-setup with recommnmark (https://github.com/rtfd/recommonmark) Sphinx-source-extension to allow including README.md into full docs would be nice. To show others that MD and ReST don't need to be mutually exclusive, but ReST is better for anything more than a page.

[svx]

@datakurre fine, fine ! :)

What would be the benefit of including the README into /docs ?
Usually a README is/should be different written than your docs intro or something else.

With/In a README you deliver 'only' certain information in a short version, like a very short summary on a book cover, where you link to deeper info which will be in /docs.

[datakurre]

@svx Agreed. Then its even easier. Probably I was just looking for an excuse to try that Sphinx markdown reader.

[svx]

@datakurre :)

[ebrehault]

Implementation is here: https://github.com/plone/plone.restapi-angular

[svx]

@ebrehault Would it be possible to rewrite the README to follow https://docs.plone.org/about/documentation_styleguide.html#readme-example ?

[ebrehault]

done

[svx]

Thanks !!!!!!