docs: updated docs

docs/README.md

@@ -0,0 +1,6 @@
+# Documentation
+
+- [Features](./feature/README.md)
+- [Design Goals](./design-goals/README.md)
+- [Contributing](./contribute/README.md)
+- [Ontology](./ontology/README.md)

docs/design-goals/README.md

@@ -0,0 +1,81 @@
+# Design Goals
+
+Create a tool that can extract information from any source and generate
+professional documentation from it either as a document or a static website.
+
+Primary focus is to document ontologies and knowledge graphs but ultimately
+to document "knowledge" in the broadest sense of the word.
+
+> [!NOTE]
+>
+> An additional angle that will be explored is how to use the tool to generate
+> content for LLM agents to consume.
+
+## Robustness
+
+**Robustness** is the number one priority:
+
+- [ ] The program should never panic.
+- [ ] The program should never enter an inconsistent state.
+- [ ] The program should never crash.
+
+## Performance
+
+**Performance** is a close second, the program should be fast, so that:
+
+- [ ] It can scan large knowledge graphs or other large amounts of data
+      within a reasonable amount of time (for instance within the duration
+      of a batch job that can finish in one night).
+- [ ] It can process a large number of files or git repositories for
+      documentable items in a short amount of time.
+- [ ] It will not cause much additional cost for people deciding to
+      integrate it in their CI/CD pipelines.
+
+## Scalability
+
+- [ ] The program should use as little memory as possible and be designed
+      to leverage streamed processing where appropriate allowing it to scale
+      to any size of data.
+- [ ] The program should be designed to be easily parallelizable or run things
+      concurrently.
+
+## Extensibility
+
+- [ ] The program should be designed to be easily extensible to add new
+      features or documentable items. It features a generic documentation model
+      that can be constructed by "plugins" that will implement the logic to
+      extract information from the data and transform it into documentation
+      components such as "chapters", "sections", "tables", "lists", etc in
+      the documentation model.
+
+- [ ] On the output side, many different types of documentation can be generated
+      from the same documentation model. For instance, a documentation model can
+      be exported to a set of markdown files, to a set of html files, to a
+      set of json files, etc.
+
+  - [ ] [typst files that are used to generate professional PDFs](../feature/target-typst.md)
+  - [ ] json files that can be used for further processing or
+        feeding into a search engine.
+  - [ ] [markdown files that can be used for further processing by tools
+        like MkDocs](../feature/target-markdown-for-mkdocs.md)
+  - [ ] [reStructuredText files that can be used for further processing by tools
+        like Sphinx](../feature/target-rst-for-sphinx.md)
+
+- [ ] Most of the logic of the program will be published as a library, so that
+      it can be reused in other projects.
+
+# Configurability
+
+- [ ] The program should be configurable through configuration files.
+- [ ] The program should be configurable through environment variables.
+- [ ] The program should be configurable through command line arguments.
+- [ ] The program should be configurable through source data annotations.
+- [ ] The program should be configurable through code.
+
+## Ease of use
+
+- [ ] The program should be designed to be easy to understand, so that:
+  - [ ] People can easily understand how to implement their own plugins if
+        they need custom logic.
+  - [ ] People can understand what is the output of the program and how to
+        use it.

docs/feature/README.md

@@ -24,8 +24,8 @@ Things to document can come from:
 
 ### HTML
 
-- [markdown for mkdocs](./target-markdown-for-mkdocs)
-- [markdown for sphinx](./target-markdown-for-sphinx)
+- [markdown (.md) files for MkDocs](./target-markdown-for-mkdocs)
+- [reStructuredText (.rst) files for sphinx](./target-rst-for-sphinx)
 
 ### PDF
 

docs/feature/target-markdown-for-mkdocs.md

@@ -4,3 +4,8 @@
 Idea
 
 Generate MkDocs compliant markdown documentation.
+
+## Links
+
+- [MkDocs](https://www.mkdocs.org/)
+- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)

docs/feature/target-typst.md

@@ -1,12 +1,17 @@
 # Target — typst
 
-[!NOTE] Status
-Idea
+> [!NOTE] Status
+> Idea
 
 Generate [typst](https://typst.app) files and a resulting PDF.
 
->[!IMPORTANT]
->Typst is built with Rust itself which means that it
->is very easy to include it as part of grapharch,
->allowing us to output PDFs without requiring any
->additional tool installations.
+> [!IMPORTANT]
+> Typst is built with Rust itself which means that it
+> is very easy to include it as part of grapharch,
+> allowing us to output PDFs without requiring any
+> additional tool installations.
+
+## Links
+
+- [Typst](https://typst.app/)
+- [Typst Docs](https://typst.app/docs/)

docs/ontology/README.md

@@ -0,0 +1,9 @@
+# Ontology
+
+> [!NOTE] Status
+>
+> This is a work in progress.
+> At the moment this is all extremely basic and not yet used, just a placeholder.
+
+- [documentation.ttl](./documentation.ttl)
+- [doc-component-categories.ttl](./doc-component-categories.ttl)