Improved docs of Plone REST API JavaScript Client

Hrittik20 commented 4 months ago

Issue: #5491

netlify[bot] commented 4 months ago

Deploy Preview for plone-components ready!

Name	Link
Latest commit	80bf229731ca3f02019bfc2683184a20b25f70dd
Latest deploy log	https://app.netlify.com/sites/plone-components/deploys/65a6badc9cc346000859258a
Deploy Preview	https://deploy-preview-5576--plone-components.netlify.app
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify[bot] commented 4 months ago

Deploy Preview for volto ready!

Name	Link
Latest commit	80bf229731ca3f02019bfc2683184a20b25f70dd
Latest deploy log	https://app.netlify.com/sites/volto/deploys/65a6badcff454400082ce701
Deploy Preview	https://deploy-preview-5576--volto.netlify.app/recipes/developing-a-project.html
Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

mister-roboto commented 4 months ago

@Hrittik20 you need to sign the Plone Contributor Agreement to merge this pull request.

Learn about the Plone Contributor Agreement: https://plone.org/foundation/contributors-agreement

stevepiercy commented 4 months ago

@Hrittik20 did you sign and return the Plone Contributor Agreement? When you are notified that you have been added to the Contributors Team, please add a comment to let us know.

Hrittik20 commented 4 months ago

@stevepiercy Yes, I have recieved the agreement in my email.

stevepiercy commented 4 months ago

@Hrittik20 then there is a mismatch between your email registered in GitHub and that which you submitted in your Plone Contributor Agreement. They must match, else @mister-roboto will forever nag you to sign the Plone Contributor Agreement. Please make sure they match, or add an email to your GitHub account that matches what you submitted.

Hrittik20 commented 4 months ago

@stevepiercy I checked but my email and my github username is correct. So I dont know why its not working.

stevepiercy commented 4 months ago

@Hrittik20 please contact agreements@plone.org and ask what happened. Perhaps they made a typo?

stevepiercy commented 3 months ago

@Hrittik20 sorry for the long delay, and thank you for your patience. I chatted with @sneridagh last week, and we came up with a plan.

First, take a look at Endpoints in the Plone REST API docs. Note that these endpoints correspond to the client methods, sort of.

Using Adding URL aliases in bulk, we want to add a new tab to the four existing tabs, "JavaScript", that would show the JavaScript client method createAliasesMutation that the developer would use to call the Plone REST API endpoint. Thus the battle of trying to format and describe the data structure would be replaced with a link to that REST API endpoint.

@sneridagh did I capture that correctly? My notes are vague, and I realized that this plan might need some refinement and further discussion. Please verify.

Hrittik20 commented 3 months ago

@stevepiercy Can you tell me a bit more about how I can add new tab to the existing tabs using "Adding URL aliases in bulk"?

stevepiercy commented 3 months ago

@Hrittik20 assuming you cloned the documentation repo, you should also have the plone.restapi repo in a submodule. Endpoint documentation is located at submodules/plone.restapi/docs/source/endpoints.

There are two Sphinx extensions that enable the tabs and examples. From requirements.txt:

sphinxcontrib.httpdomain  # plone.restapi
sphinxcontrib.httpexample  # plone.restapi

More information:

Hrittik20 commented 3 months ago

@stevepiercy Okay. Should I use "sphinx-tabs" extension to build the new tabs or is there any other better way?

stevepiercy commented 3 months ago

The extension sphinxcontrib-httpexample which I mentioned provides tabs already. It could be extended for the JavaScript client.

sneridagh commented 2 months ago

@stevepiercy yeah, you explained it right. What we said also is that afterwards we could remove all the endpoints docs here, to point to the main endpoints documentation in plone.restapi, and here leave only the introduction, basics, install.

Hrittik20 commented 2 months ago

@stevepiercy Can you guide me in extending sphinxcontrib-httpexample for JavaScript client? Currently, I think it mostly supports curl, wget, python-requests, and httpie. Your insights would be appreciated.

stevepiercy commented 2 months ago

@Hrittik20 I have zero familiarity with how it works. I am just an end user. In general, would duplicate what is done for one of the other request methods, writing code and tests.

You could either investigate on your own, ask on the Community Forum, or contact the maintainers (https://pypi.org/project/sphinxcontrib-httpexample/) or contributors to it.

Hrittik20 commented 2 months ago

@stevepiercy To add a JavaScript client tab, I would need to modify sphinxcontrib-httpexample. We can either create a modified fork of sphinxcontrib-httpexample or make a local package. I think a local package would be a better option. What do you think?

Additionally, the JavaScript client tab should display the string 'createAliasesMutation', correct?

stevepiercy commented 2 months ago

@Hrittik20 you will need to create a fork of that project, just as you always do when contributing to an open source software project. See https://collective.github.io/ for how to contribute to the organization's repos. You could follow Plone's contributing documentation, as Collective's is somewhat lacking.

It would also be a good idea to create a new issue in that repo, referencing this pull request, to explain what we would like to do. There are a couple of old issues from 2017 suggesting the addition of other language's request tools, too.

Hrittik20 commented 2 months ago

@stevepiercy Is this okay?

Capture

stevepiercy commented 2 months ago

@Hrittik20 yup, that's a good start.

Hrittik20 commented 2 months ago

@stevepiercy Should I create a pull request, or are there additional changes I need to make?

stevepiercy commented 2 months ago

I would expect to see more content in the tab, such as a request body, similar to the http tab's content, but formatted for the JavaScript library. See example https://6.docs.plone.org/plone.restapi/docs/source/endpoints/aliases.html#adding-new-url-aliases-for-a-page

Hrittik20 commented 2 months ago

@stevepiercy I made the modifications. Is this better?

Capture

stevepiercy commented 2 months ago

@Hrittik20 yes, it looks much better. It would be good to format the JSON object for readability, similar to what the http request and response do. Example: https://6.docs.plone.org/plone.restapi/docs/source/endpoints/aliases.html#adding-new-url-aliases-for-a-page

Hrittik20 commented 2 months ago

@stevepiercy It took me a while to figure out the format 😅

Capture

stevepiercy commented 2 months ago

Yeah, I saw your SO post. 😄

Is it ready for a pull request? It does not have to be perfect, as the maintainers may make suggestions during review.

Hrittik20 commented 2 months ago

Yes, I will make the pull request for sphinx now

stevepiercy commented 2 months ago

@Hrittik20 the PR should not go in Sphinx, but in the Sphinx extension https://github.com/collective/sphinxcontrib-httpexample.

Hrittik20 commented 2 months ago

@stevepiercy The pull request has been merged. You can also check the documentation at https://sphinxcontrib-httpexample.readthedocs.io/en/latest/usage.html for the JavaScript tab usage.

stevepiercy commented 2 months ago

@Hrittik20 I am super excited! @sneridagh check out the new JavaScript tab that we can now apply to the REST API docs.

https://sphinxcontrib-httpexample.readthedocs.io/en/latest/usage.html

My work this week is crazy busy, but I look forward to the next steps. Thank you! Thank you! Thank you!

stevepiercy commented 2 months ago

Linking to PRs for future reference:

sneridagh commented 2 months ago

@Hrittik20 looks already good! Can't wait to see the final outcome!

Did you think about how to pass the data to the tab? We can discuss the options that we have. For starters, they should not collide with the existing ones, and complement them in a way that is not intrusive and break them.

FTR, in case you don't stumbled upon them:

https://github.com/plone/plone.restapi/blob/main/src/plone/restapi/tests/test_documentation.py#L2411-L2417

in this test is how we generate the sphinx extension data. Then the docs consume it:

https://github.com/plone/plone.restapi/blob/main/docs/source/endpoints/vocabularies.md?plain=1#L90-L92

Maybe we can include another marker like :javascript: then pass a file with the code? Wondering if we could autogenerate it out of the other existing information... I will think about it.

plone / volto