[Idea] Documentation Catalogues

[clsource]

Documentation Catalogues

Hello since Onyx have proper documentation comments in the parser, I think it can use documentation catalogues similar to Swift Docc tool.

I tried to create something for Odin, but since it does not support documentation comments (only normal comments with special structure), it proved to be quite difficult without parser modification.

But I learned alot about how to structure documentation catalogues.

You can check an example output here (that was manually created to test the structure)

https://odin-arsenal.github.io/gungnir/SlothCreator/

A documentation catalogue consist of this structure:

• A directory where all the content will be stored (markdown files and resources)
• The mdbook and configuration files for generating the output.
• An articles directory to store different complementary documentation.
• A tutorials directory to store step by step instructions on how to use the packages and apis.
• A extensions directory. Is a special directory that follows the same project structure. Can overwrite the documentation for any file, method, structure, enum, constant. The tool would read this directory and use these files for rendering the markdown instead of the contents of doc comments.

Normally it will have a structure similar to this:

.
├── LICENSE.md
├── README.md
├── book.toml
├── preprocessors
│   └── set_version.py
├── run
├── src
│   ├── README.md
│   ├── SUMMARY.md
│   ├── articles
│   ├── extensions
│   │   └── core
│   │       ├── overview.md
│   │       └── slice
│   │           ├── overview.md
│   │           └── slice.odin.d
│   │               ├── overview.md
│   │               ├── examples
│   │               │   ├── reduce-example1
│   │               │   │   └── example.odin.txt
│   │               │   └── reduce_reverse-example1
│   │               │       └── example.odin.txt
│   │               ├── reduce.md
│   │               └── reduce_reverse.md
│   ├── resources
│   │   └── odin.jpg
│   └── tutorials
└── theme
    ├── book.js
    └── highlight.js

State of the art

The current documentation tool https://github.com/onyx-lang/onyx-doc-gen is awesome to create API documentation, but it have some disadvantages:

1. Can only create HTML with a specific template. By using markdown it can be converted to other formats (using pandoc) and create other artifacts such as PDF or Epub. Even a tar file can be created to easily send over the network documentation and open them easily.

2. The current implementation is limited to docs inside the code. Extending the documentation with complementary articles and tutorials is an important tool to improve adoption of the packages and well usage of APIS.

3. Too much different contexts on a single page. The separation in a single page per context can improve the reader experience when looking for symbols, using the mdbook tools we can create confortable documentation that does not overwhelm the reader.

4. Separation of concerns, the core apis are mixed with the user package apis. It would be a good idea to generate documentation per package, that way it would be easier to version each component.

By using a documentation catalogues and mdbook we can create something similar to Hexdocs

Also inspired by Swift Docc the renderer can recognize additional keywords to improve documentation.

Keywords

The renderer could support special keywords inside doc comments that can render them in special formats or be used to organize different sections in the comment.

These are: Attention, Author, Authors, Bug, Complexity, Copyright, Date, Experiment, Important, Invariant, Note, Postcondition, Precondition, Remark, Requires, See, SeeAlso, Since, TODO, Version, Warning, Throws.

• Attributions (author, authors, copyright, date) create a documentation trail for authorship.

• Availability (since, version) specifies when material was added to the code or updated, enabling you to lock down both release conformance and real-world time.

• Admonitions (attention, important, note, remark, warning) caution about use. These establish design rationales and point out limitations and hazards.

• Development State (bug, TODO, experiment) express progress of ongoing development, marking out areas needing future inspection and refinement.

• Implementation qualities (complexity) express a code’s time and space complexity.

• Functional Semantics (precondition, postcondition, requires, invariant) detail predicates about argument values before and after calls. Preconditions and requirements limit the values and conditions under which the code should be accessed. Postconditions specify observable results that are true after execution.

• Cross Reference (see) enables you to point out related material to add background to the documented implementation.

• Throws are used to document what errors can be thrown and why. These appear alongside parameters and return descriptions.

• Examples are used to create documentation tests. These serves as an example code that can be included in the test suit.

Documentation Tests

The same idea from Elixir Doctests and Rust Doctest.

Supports executing your documentation examples as tests. This makes sure that examples within your documentation are up to date and working.

A documentation test can be composed of two component. One is the code block that contains the onyx code to execute. Followed by a text block that contains the expected result.

```
// onyx code
```
```text
42
```

Reference: Erica Sadun's Swift Documentation

[brendanfh]

I completely agree that a more comprehensive documentation generation tool is needed for Onyx. The current documentation generation was the best I could make with how the compiler was structured at the time. I think with some changes I am working on right now in the toolchain, it will be much easier to create a separate tool that can do this generation.

I am also very interested in the Doctests that you mentioned. I think they will be relatively easy to implement while creating the new documentation generation tool.

All around I think this would be a great addition to the Onyx toolchain.

[clsource]

I implemented SlothCreator example in Onyx for testing

SlothCreator.zip

[clsource]

A related link for developer docs: https://diataxis.fr/

Diátaxis is a way of thinking about and doing documentation.
tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs.