plone
Improved docs of Plone REST API JavaScript Client
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] avatar](https://avatars.githubusercontent.com/in/13473?v=4 "Published by a pub.dev verified publisher"){kind=small}
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.
@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
@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 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.
@stevepiercy I checked but my email and my github username is correct. So I dont know why its not working.
@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.
@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"?
@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:
- https://pypi.org/project/sphinxcontrib-httpdomain/
- https://pypi.org/project/sphinxcontrib-httpexample/
@stevepiercy Okay. Should I use "sphinx-tabs" extension to build the new tabs or is there any other better way?
The extension sphinxcontrib-httpexample which I mentioned provides tabs already. It could be extended for the JavaScript client.
@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.
@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.
@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.
@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?
@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.
@stevepiercy Should I create a pull request, or are there additional changes I need to make?
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 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
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 the PR should not go in Sphinx, but in the Sphinx extension https://github.com/collective/sphinxcontrib-httpexample.
@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.
@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!