Create PURL services documentation

[pombredanne]

We should create and publish on RTD a comprehensive installation and usage documentation for the various PURL-based services of PurlDB. This should be backed by a publicly accessible demo system

• purl2all: Create doc for PURL services accessible through the API #445 with PR in Add documentation for PurlDB #241 #456
• purl2all: Create doc for PURL services accessible through the purlcli #446 merged with Update purldb-toolkit and related README files #249 #450
• Validate and document that we use the public demo system at https://public.purldb.io/api/ #448
• Create intro, base documentation for the PURL services. #457

[pombredanne]

We would need some doc for the purlcli and some doc for each of the endpoints

[pombredanne]

@johnmhoran @AyanSinhaMahapatra is this something you guys could get started?
Overall we would need some doc in the same style and structure as ScanCode.io?

[johnmhoran]

@pombredanne I just saw this. Yes, I'd be happy to work with @AyanSinhaMahapatra on this -- we can start by finding a time to discuss general structure and content and see how the ScanCode.io RTD informs our work. I'll also need to learn what the various endpoints do and how we use them.

Unless you suggest otherwise, I would like to get a bit more of my PURL CLI work out of the way first since I'm still wrestling with the urls command, have not yet fully changed the four existing commands to the SCTK-like data structure, and have more commands to add (scan and git -- and perhaps others?).

[pombredanne]

Some status update:

• We created and published the API definitions documentation see code cfc1c96

• This is deployed on public.purldb.io at /api/docs for the docs and the schema is at /api/. See the live API doc https://private.purldb.io/api/docs/ and schema https://private.purldb.io/api/schema

• We also updated the built-in documentation of end points accordingly

[johnmhoran]

@pombredanne @AyanSinhaMahapatra As noted a bit earlier in purldb PR 436, I've added details to the existing purldb-toolkit RTD page re the use of the four current PURLCLI tools, with a mix of command and output examples and several related notes. The .rst is here:

https://github.com/nexB/purldb/blob/f49eff87ae9a4226584096498836de7d5015f6a2/purldb-toolkit/README.rst

The initial description above for this issue also says This should be backed by a publicly accessible demo system. What is this? Any examples or articles or a design doc?

[pombredanne]

All done, now published at https://aboutcode.readthedocs.io/projects/PURLdb/en/latest/index.html