documentation.md 2.16 KB
Newer Older
1
2
3
4
5
6
# Documentation

Welcome to the meta section of our documentation where we document how to do documentation!

Edit or add.  That's the primary instruction.  You can edit directly on [gitlab.com/agaric/documentation](https://gitlab.com/agaric/documentation) (for example, the edit link on this page takes you to [gitlab.com/agaric/documentation/blob/master/documentation.md](https://gitlab.com/agaric/documentation/blob/master/documentation.md)).  If you aren't a member of Agaric, GitLab will helpfully offer to fork the documentation to your own namespace so that you can make a merge request with your documentation suggestion.

7
8
```{tip}
This documentation page is a good one to copy or refer to for an example of MyST formatting.  And of course anyone can come and clean up formatting later.
9
10
```

11
12
## Where to post what

13

Chris Thompson's avatar
Chris Thompson committed
14
We like [Gitlab's approach](https://about.gitlab.com/handbook/git-page-update/#where-should-content-go): If you're not sure where to put something in documentation, or if it even is documentation, [write a blog post](https://agaric.com/node/add/blog).  Or even, in the Agaric context, just throw it in a [raw note](https://gitlab.com/agaric/raw-notes) (this private repository automatically publishes non-draft notes publicly to [agaric.gitlab.io/raw-notes](https://agaric.gitlab.io/raw-notes/)).
15
16
17
18
19

Somewhere is better than nowhere.

Don't worry about [translation](translation).

20
## Guidelines
21
22
23
24
25
26
27
28
29
30

* Document closest to where people work:
   * In README.md files or otherwise in the code repository for developers.
   * In the site itself for site managers and content editors, or alternatively in an organization's already established locations.
* Topics which are of general application can be abstracted, put in this repository, and linked to at this documentation.

```{note}
In doing documentation we are living our [values](values) of encouraging continuous learning, appreciating new ideas, giving back to the communities we are part of, and valuing long-term relationships.
```

31
## Local preview
32

33
34
35
36
37
38
39
40
41
### Setup

```bash
sudo apt install python3-sphinx
pip3 install -r requirements.txt
```

### Generating

42
43
44
45
46
Running this documentation locally:

```bash
sphinx-build -b html . _build/html
```