[FEATURE] Built-in extension documentation

[PhillippOhlandt]

The idea is to provide real documentation pages for extensions. That means they can split it over several pages and don't need to put everything in the readme.

For simplicity, the documentation markdown files will live inside the git repository so everyone can contribute changes and we don't have to build a whole management system :)

Documentation versioning could be used via git itself but that makes later changes a bit difficult so I suggest a filesystem based versioning system.

Repository Structure

├── README.md
├── composer.json
├── config
├── docs
│   └── v1.0
│       ├── contribution.md
│       ├── extend.md
│       ├── installation.md
│       ├── introduction.md
│       ├── menu.yml
│       └── usage.md
├── phpunit.xml.dist
├── src
├── templates
├── tests
└── web

You can see, the git repository contains a docs folder. Inside this folder is one folder for each major/minor (depending on the needs) version of the extension. The version folder contains a menu.yml file which defines the order and names of the specific documentation pages.

menu.yml

- title: Introduction
  file: introduction.md
- title: Installation
  file: installation.md
- title: Usage
  file: usage.md
- title: Extend the Extension Functionality
  file: extend.md
- title: Contribution
  file: contribution.md

The menu.yml is just a simple definition file for the navigation.

Note: The files above are just as an example. It's completely up to the extension developer to define the documentation structure for his extension.

Implementation inside the Store

I would suggest the following URL structure for a documentation page: https://extensions.bolt.cm/view/ohlandt/user-profiles/docs/v1/introduction So it almost mimics the file structure inside the repository, except that we removed the .md for the URL.

It will also make sense to save the whole documentation somewhere so we don't have to pull it "live" from Github. It would be updated on every update (manually or via hook) in the store.

---

What I described above is my idea of an easy implementation. But I am also open to suggestions and other ideas :)

[GwendolenLynch]

For the docs in the extension's repo, just stick with branching for versions. Obviously for our cached/served files we can compile that hierarchically.

[PhillippOhlandt]

@GawainLynch how would you branch it? one branch for every version so we have separate docs branches on the extension repo?