/sandbox-well-known-docs

Primary LanguagePythonBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

Documentation for .well-known endpoints on dataspaces

This repository is used to document the different .well-known URLs used on dataspaces and to convert and host those as a human friendly web page.

Structure

  • ./src/ - Source files containing Python/Pydantic models describing the different .well-known URLs and the data they contain.
  • ./schemas/ - Intermediate JSON Schema files generated from the above by the tooling provided in this repo.
  • ./html/ - Final static files generated by the tooling that are hosted using GitHub pages.
  • ./main.py - The converter used to convert the source files to JSON Schema and HTML + CSS + JS.
  • ./.github/workflows/deploy.yaml - GitHub Action to build and deploy to GitHub Pages.

Development

Generic pre-requisites for development

Install dependencies with:

poetry install

Usage

These source files can be converted to HTML files by running:

poetry run convert-src-to-html

Testing locally

cd html
python -m http.server

Then check the files at: http://localhost:8000/

Adding new files

In order to add new files to the documentation:

  1. Add a new .py file in ./src.
  2. Define Python/pydantic model(s) in the file.
  3. Assign the class you want to be documented to the ROOT variable.