mirror of
https://github.com/evennia/evennia.git
synced 2026-03-16 21:06:30 +01:00
Clean up contrib docs, autogeneration
This commit is contained in:
Griatch
parent
b922cf9b3c
commit
e96bbb4b86
94 changed files with 4126 additions and 2536 deletions
|
|
@ -12,10 +12,10 @@ in `evennia/docs/source/` and make a PR for it!
|
|||
The documentation source files are `*.md` (Markdown) files found in `evennia/docs/source/`.
|
||||
Markdown files are simple text files that can be edited with a normal text editor. They can also
|
||||
contain raw HTML directives (but that is very rarely needed). They use
|
||||
the [Markdown][commonmark] syntax with [MyST extensions][MyST].
|
||||
the [Markdown][commonmark] syntax with [MyST extensions][MyST].
|
||||
|
||||
```{important}
|
||||
You do _not_ need to be able to test/build the docs locally to contribute a documentation PR.
|
||||
You do _not_ need to be able to test/build the docs locally to contribute a documentation PR.
|
||||
We'll resolve any issues when we merge and build documentation. If you still want to build
|
||||
the docs for yourself, instructions are [at the end of this document](#building-the-docs-locally).
|
||||
```
|
||||
|
|
@ -126,15 +126,15 @@ The link syntax is `[linktext](url_or_ref)` - this gives a clickable link [linkt
|
|||
|
||||
### Internal links
|
||||
|
||||
Most links will be to other pages of the documentation or to Evennia's API docs. Each document
|
||||
heading can be referenced. The reference always starts with `#`. The heading-name is always
|
||||
given in lowercase and ignores any non-letters. Spaces in the heading title are replaced with
|
||||
Most links will be to other pages of the documentation or to Evennia's API docs. Each document
|
||||
heading can be referenced. The reference always starts with `#`. The heading-name is always
|
||||
given in lowercase and ignores any non-letters. Spaces in the heading title are replaced with
|
||||
a single dash `-`.
|
||||
|
||||
As an example, let's assume the following is the contents of a file `Menu-stuff.md`:
|
||||
|
||||
```
|
||||
# Menu items
|
||||
# Menu items
|
||||
|
||||
Some text...
|
||||
|
||||
|
|
@ -143,28 +143,28 @@ Some text...
|
|||
Some more text...
|
||||
```
|
||||
|
||||
- From _inside the same file_ you can refer to each heading as
|
||||
- From _inside the same file_ you can refer to each heading as
|
||||
|
||||
[menus](#menu-items)
|
||||
[example](#a-yesno-example)
|
||||
|
||||
- From _another file_, you reference them as as
|
||||
- From _another file_, you reference them as as
|
||||
|
||||
[menus](Menu-Stuff.md#menu-items)
|
||||
[example](Menu-Stuff.md#a-yesno-example)
|
||||
|
||||
> It's fine to not include the `.md` file ending in the reference. The Evennia doc-build process
|
||||
> It's fine to not include the `.md` file ending in the reference. The Evennia doc-build process
|
||||
> will correct for this (and also insert any needed relative paths in the reference).
|
||||
|
||||
### API links
|
||||
### API links
|
||||
|
||||
The documentation contains auto-generated documentation for all of Evennia's source code. You
|
||||
can direct the reader to the sources by just giving the python-path to the location of the
|
||||
The documentation contains auto-generated documentation for all of Evennia's source code. You
|
||||
can direct the reader to the sources by just giving the python-path to the location of the
|
||||
resource under the `evennia/` repository:
|
||||
|
||||
[DefaultObject](evennia.objects.objects.DefaultObject)
|
||||
|
||||
[DefaultObject](evennia.objects.objects.DefaultObject) <- like this!
|
||||
[DefaultObject](evennia.objects.objects.DefaultObject) <- like this!
|
||||
|
||||
Note that you can't refer to files in the `mygame` folder this way. The game folder is generated
|
||||
dynamically and is not part of the api docs. Refer to the parent classes in `evennia` where possible.
|
||||
|
|
@ -180,12 +180,12 @@ These are links to resources outside of the documentation. We also provide some
|
|||
- `[linkname](github:develop/evennia/objects.objects.py` - this points to code in the `develop` branch.
|
||||
- `[make an issue](github:issue)` - this is a shortcut to the Evennia github issue-creation page.
|
||||
|
||||
> Note that if you want to refer to code, it's usually better to [link to the API](#api-links) as
|
||||
> Note that if you want to refer to code, it's usually better to [link to the API](#api-links) as
|
||||
> described above.
|
||||
|
||||
### Urls/References in one place
|
||||
|
||||
Urls can get long and if you are using the same url/reference in many places it can get a
|
||||
Urls can get long and if you are using the same url/reference in many places it can get a
|
||||
little cluttered. So you can also put the url as a 'footnote' at the end of your document.
|
||||
You can then refer to it by putting your reference within square brackets `[ ]`. Here's an example:
|
||||
|
||||
|
|
@ -202,25 +202,25 @@ This is a [clickable link][mylink]. This is [another link][1].
|
|||
|
||||
This makes the main text a little shorter.
|
||||
|
||||
## Tables
|
||||
## Tables
|
||||
|
||||
A table is done like this:
|
||||
A table is done like this:
|
||||
|
||||
````
|
||||
````
|
||||
| heading1 | heading2 | heading3 |
|
||||
| --- | --- | --- |
|
||||
| --- | --- | --- |
|
||||
| value1 | value2 | value3 |
|
||||
| | value 4 | |
|
||||
| value 5 | value 6 | |
|
||||
````
|
||||
|
||||
| heading1 | heading2 | heading3 |
|
||||
| --- | --- | --- |
|
||||
| --- | --- | --- |
|
||||
| value1 | value2 | value3 |
|
||||
| | value 4 | |
|
||||
| value 5 | value 6 | |
|
||||
|
||||
As seen, the Markdown syntax can be pretty sloppy (columns don't need to line up) as long as you
|
||||
As seen, the Markdown syntax can be pretty sloppy (columns don't need to line up) as long as you
|
||||
include the heading separators and make sure to add the correct number of `|` on every line.
|
||||
|
||||
|
||||
|
|
@ -252,7 +252,7 @@ Everything within these backticks will be verbatim.
|
|||
|
||||
### Code blocks
|
||||
|
||||
A special 'verbatim' case is code examples - we want them to get code-highlighting for readability.
|
||||
A special 'verbatim' case is code examples - we want them to get code-highlighting for readability.
|
||||
This is done by using the triple-backticks and specify which language we use:
|
||||
|
||||
````
|
||||
|
|
@ -281,22 +281,22 @@ class CmdEcho(Command):
|
|||
|
||||
For examples of using the Python command-line, use `python` language and `>>>` prompt.
|
||||
````
|
||||
```python
|
||||
```python
|
||||
>>> print("Hello World")
|
||||
Hello World
|
||||
```
|
||||
````
|
||||
|
||||
```python
|
||||
```python
|
||||
>>> print("Hello World")
|
||||
Hello World
|
||||
```
|
||||
|
||||
When showing an in-game command, use the `shell` language type and `>` as the prompt.
|
||||
When showing an in-game command, use the `shell` language type and `>` as the prompt.
|
||||
Indent returns from the game.
|
||||
|
||||
````
|
||||
```shell
|
||||
````
|
||||
```shell
|
||||
> look at flower
|
||||
Red Flower(#34)
|
||||
A flower with red petals.
|
||||
|
|
@ -310,19 +310,19 @@ Indent returns from the game.
|
|||
```
|
||||
|
||||
|
||||
For actual shell prompts you can either use `bash` language type or just indent the line.
|
||||
Use `$` for the prompt when wanting to show what is an input and what is an output, otherwise
|
||||
For actual shell prompts you can either use `bash` language type or just indent the line.
|
||||
Use `$` for the prompt when wanting to show what is an input and what is an output, otherwise
|
||||
skip it - it can be confusing to users not that familiar with the command line.
|
||||
|
||||
````
|
||||
```bash
|
||||
````
|
||||
```bash
|
||||
$ ls
|
||||
evennia/ mygame/
|
||||
```
|
||||
evennia start --log
|
||||
````
|
||||
|
||||
```bash
|
||||
```bash
|
||||
$ ls
|
||||
evennia/ mygame/
|
||||
```
|
||||
|
|
@ -330,13 +330,13 @@ evennia/ mygame/
|
|||
evennia start --log
|
||||
|
||||
|
||||
## MyST directives
|
||||
## MyST directives
|
||||
|
||||
Markdown is easy to read and use. But while it does most of what we need, there are some things it's
|
||||
not quite as expressive as it needs to be. For this we use extended [MyST][MyST] syntax. This is
|
||||
on the form
|
||||
not quite as expressive as it needs to be. For this we use extended [MyST][MyST] syntax. This is
|
||||
on the form
|
||||
|
||||
````
|
||||
````
|
||||
```{directive} any_options_here
|
||||
|
||||
content
|
||||
|
|
@ -347,7 +347,7 @@ content
|
|||
|
||||
#### Note
|
||||
|
||||
This kind of note may pop more than doing a `> Note: ...`.
|
||||
This kind of note may pop more than doing a `> Note: ...`.
|
||||
|
||||
````
|
||||
```{note}
|
||||
|
|
@ -436,7 +436,7 @@ for example to remind the reader of some concept relevant to the text.
|
|||
- There can be bullet lists
|
||||
- in here.
|
||||
|
||||
Separate sections with
|
||||
Separate sections with
|
||||
|
||||
an empty line.
|
||||
```
|
||||
|
|
@ -447,12 +447,12 @@ an empty line.
|
|||
- There can be bullet lists
|
||||
- in here.
|
||||
|
||||
Separate sections with
|
||||
Separate sections with
|
||||
|
||||
an empty line.
|
||||
```
|
||||
|
||||
Hint: If wanting to make sure to have the next header appear on a row of its own (rather than
|
||||
Hint: If wanting to make sure to have the next header appear on a row of its own (rather than
|
||||
squeezed to the left of the sidebar), one can embed a plain HTML string in the markdown like so:
|
||||
|
||||
```html
|
||||
|
|
@ -464,7 +464,7 @@ squeezed to the left of the sidebar), one can embed a plain HTML string in the m
|
|||
### A more flexible code block
|
||||
|
||||
The regular Markdown Python codeblock is usually enough but for more direct control over the style, one
|
||||
can also use the `{code-block}` directive that takes a set of additional `:options:`:
|
||||
can also use the `{code-block}` directive that takes a set of additional `:options:`:
|
||||
|
||||
````
|
||||
```{code-block} python
|
||||
|
|
@ -536,7 +536,7 @@ same as Markdown.
|
|||
The source code docstrings will be parsed as Markdown. When writing a module docstring, you can use Markdown formatting,
|
||||
including header levels down to 4th level (`#### SubSubSubHeader`). After the module documentation it's
|
||||
a good idea to end with four dashes `----`. This will create a visible line between the documentation and the
|
||||
class/function docs to follow. See for example [the Traits docs](evennia.contrib.traits).
|
||||
class/function docs to follow. See for example [the Traits docs](evennia.contrib.rpg.traits).
|
||||
|
||||
All non-private classes, methods and functions must have a Google-style docstring, as per the
|
||||
[Evennia coding style guidelines][github:evennia/CODING_STYLE.md]. This will then be correctly formatted
|
||||
|
|
@ -545,8 +545,8 @@ into pretty api docs.
|
|||
## Technical
|
||||
|
||||
Evennia leverages [Sphinx][sphinx] with the [MyST][MyST] extension, which allows us
|
||||
to write our docs in light-weight Markdown (more specifically [CommonMark][commonmark], like on github)
|
||||
rather than Sphinx' normal ReST syntax. The `MyST` parser allows for some extra syntax to
|
||||
to write our docs in light-weight Markdown (more specifically [CommonMark][commonmark], like on github)
|
||||
rather than Sphinx' normal ReST syntax. The `MyST` parser allows for some extra syntax to
|
||||
make us able to express more complex displays than plain Markdown can.
|
||||
|
||||
For [autodoc-generation][sphinx-autodoc] generation, we use the sphinx-[napoleon][sphinx-napoleon]
|
||||
|
|
@ -729,4 +729,4 @@ available at https://evennia.github.io/evennia/latest/.
|
|||
[linkdemo]: #Links
|
||||
[retext]: https://github.com/retext-project/retext
|
||||
[grip]: https://github.com/joeyespo/grip
|
||||
[pycharm]: https://www.jetbrains.com/pycharm/
|
||||
[pycharm]: https://www.jetbrains.com/pycharm/
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue