Project

General

Profile

Actions

Bug #19929

open

Improve documentation in the discovery document

Added by Brett Smith 2 months ago. Updated about 2 months ago.

Status:
New
Priority:
Normal
Assigned To:
-
Category:
Documentation
Target version:
Start date:
Due date:
% Done:

0%

Estimated time:
Story points:
1.0

Description

Just like every public class and method in the Python SDK should have its own docstring, every public schema, resource type, and method in the API server's discovery document should have a consistent description. SDKs in every language can use this to generate documentation.

IMO unless some other requirement overrides, description fields should follow the same Markdown formatting rules we use for Python docstrings, for the same reasons: to provide a presentation that looks good in both plaintext and HTML.


Related issues

Related to Arvados - Support #18799: Strategy to generate Python SDK docstrings based on API docsNewBrett Smith

Actions
Related to Arvados - Bug #3817: [API] Discovery document schema does not include generated fields like job dependenciesNew

Actions
Actions #1

Updated by Brett Smith 2 months ago

  • Related to Support #18799: Strategy to generate Python SDK docstrings based on API docs added
Actions #2

Updated by Brett Smith 2 months ago

  • Story points set to 1.0

Estimating one story point based on:

$ git grep -c description: services/api/app/controllers/
services/api/app/controllers/application_controller.rb:8
services/api/app/controllers/arvados/v1/collections_controller.rb:4
services/api/app/controllers/arvados/v1/container_requests_controller.rb:2
services/api/app/controllers/arvados/v1/groups_controller.rb:7
services/api/app/controllers/arvados/v1/nodes_controller.rb:2
services/api/app/controllers/arvados/v1/schema_controller.rb:31

Point being, most of the work is documenting the common methods once in schema_controller, there aren't tons of exceptions and additions beyond that.

Actions #3

Updated by Peter Amstutz about 2 months ago

  • Release set to 60
Actions #4

Updated by Brett Smith about 2 months ago

  • Release deleted (60)
  • Target version set to To be scheduled

I am proposing we do this as part of improving our documentation generally. It's been groomed. We don't have to take this approach, but I would like to at least discuss it and not postpone it automatically.

Actions #5

Updated by Brett Smith about 2 months ago

  • Related to Bug #3817: [API] Discovery document schema does not include generated fields like job dependencies added
Actions

Also available in: Atom PDF