Docs: Review API and Options functionality not listed in main api or config sections to see whether should be added to reference-style list.

[kcondon]

There are several places in the guides where api endpoints and jvm options are listed in topics but not in the configuration section or the api guides:

S3 jvm options
Shibboleth
Admin
Big Data
Other?

This ticket is to review what is there to see if this is intentional and whether it makes sense to consolidate into a reference section in addition to where the currently live.

[pdurbin]

@kcondon in pull request #6107 I tried to address this in a new "Lists of Dataverse APIs" section that looks like this:

Does this help?

I also added a new FAQ page and the question "Where is the Comprehensive List of All API Functionality?" that references #5794 and the fact that if we upgrade to Payara (#4172) we can get a complete list of API commands in Swagger/OpenAPI format. Here's how that question and answer look:

I also mentioned the Payara thing in my API talk the other day. Here are my notes from that talk: #6086 (comment)

[kcondon]

@pdurbin Seems reasonable. Minor quibble, I might adjust the SWORD description from saying a standards based approach to saying using the SWORD standard.

[poikilotherm]

Today I had to lookup some stuff in the API docs and it bothered me that it's sometime complicated to parse the information or find out that an endpoint is missing from the docs and it would be nice to have more examples.

Looking at #5794 and this issue, maybe one day we can do something like one of these:

• Go for nicer inline examples via https://github.com/collective/sphinxcontrib-httpexample
  

• Go for fancy!

  1. Document API endpoints within the code using Swagger Core and create an extensive OpenAPI definition at buildtime
  2. Use https://slatedocs.github.io/slate/#introduction to create VERY nice API docs. Not sure, but I guess Zenodo is using it, too... https://developers.zenodo.org

• Use the OpenAPI definition to add to our Sphinx-based docs via https://github.com/sphinx-contrib/openapi - but this is not really blending in with our current ideas and style.

[poikilotherm]

Today I learned about https://github.com/SAP/swagger-plugin-for-sphinx to include Swagger HTML pages within your Sphinx build.

[cmbz]

To focus on the most important features and bugs, we are closing issues created before 2020 (version 5.0) that are not new feature requests with the label 'Type: Feature'.

If you created this issue and you feel the team should revisit this decision, please reopen the issue and leave a comment.