RFC: publish the specs as a web page on ReadTheDocs

[jkowalleck]

github is great for collaborating on the specs, issuing releases, version controlling, and tracking changes. github is not that great for publishing the resulting documents.

i propose to publish the specs in a web-friendly way, so that non-tech people can read and browse the spec without the overhead of github's file browser and rendering/UI burdens.

minimal requirements

• MUST: all relevant documents are hosted as web-ages:
  • readme: https://github.com/package-url/purl-spec/blob/master/README.rst
  • purl-spec: https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst
  • purl-types: https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst
  • vers-spec: https://github.com/package-url/purl-spec/blob/master/VERSION-RANGE-SPEC.rst
• MUST: the latest (master branch) is published automatically
• MUST: have a list of contents rendered

non-requirements

• may have a machine-readable page index rendered in SEO typical way.
• no need for a fancy look-and-feel or theme: goal is to have human-readable publishing for the web - at first, we dont care for bright colors, appealing shapes and such

out-of-scopes & non-use cases

• versioned publish: since there are no releases yet, we do not need to publish a set of documents per version -- latest is enough
• providing prepress: we do not need to publish PDF or something. If needed, users can issue this via PDF/PS converters themselves, as modern browsers have this built in.
• split publishing: yes, this is a mono-repo containing the PURL-spec and the VERS-spec; anyway, we do not need to split the publishing quite yet. this might be done as soon as the release-processes of the various specs are clarified.

[jkowalleck]

this is an RFC; feel free to comment. i might modify the initial request to reflect the latest consensus. :D

---

Lets discuss requirements.

I do not want to discuss actual solutions right now. (yet, we could publish to github pages, or readthedocs.io, or something else...) (yes, we could generate via pandoc, or phinx, or rst2html, or something else...)

Anyway, if you have a solution that meats all (current) requirements, please let us know: post the URL to the publishing here 👍 and tell where we might find the CI pipelines and configs

[stevespringett]

The PURL and VERS spec will eventually be published to conform to the following formats:

• https://tc39.es/ecma262/
• https://ecma-international.org/wp-content/uploads/ECMA-262_15th_edition_june_2024.pdf

Both are generated from the same sources.

[jkowalleck]

a website like https://tc39.es/ecma262/ built on "latest" master branch would be a fitting result.

[jkowalleck]

for the record,

I have registered the fallowing RTD projects.

• https://package-url.readthedocs.org/
• https://purl-spec.readthedocs.org/

@pombredanne is invited to be an admin of these projects.