Refactor 1.0 docs with new toctree structure and inheritance
This commit is contained in:
Griatch
parent
62477eac50
commit
628afe9367
142 changed files with 3967 additions and 3024 deletions
|
|
@ -56,19 +56,19 @@ primarily be accessed as link refs (e.g. `Component/Accounts`)
|
|||
the Evennia version on a new branch.
|
||||
|
||||
|
||||
# Editing syntax
|
||||
## Editing syntax
|
||||
|
||||
The format used for Evennia's docs is [Markdown][commonmark-help] (Commonmark). While markdown
|
||||
supports a few alternative forms for some of these, we try to stick to the below forms for consistency.
|
||||
|
||||
## Italic/Bold
|
||||
### Italic/Bold
|
||||
|
||||
We generally use underscores for italics and double-asterisks for bold:
|
||||
|
||||
- `_Italic text_` - _Italic text_
|
||||
- `**Bold Text**` - **Bold text**
|
||||
|
||||
## Headings
|
||||
### Headings
|
||||
|
||||
We use `#` to indicate sections/headings. The more `#` the more of a sub-heading it is (will get
|
||||
smaller and smaller font).
|
||||
|
|
@ -82,7 +82,7 @@ smaller and smaller font).
|
|||
does not prevent it, it will make it impossible to refer to that heading uniquely.
|
||||
The Evennia documentation preparser will detect this and give you an error.
|
||||
|
||||
## Lists
|
||||
### Lists
|
||||
|
||||
One can create both bullet-point lists and numbered lists:
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ One can create both bullet-point lists and numbered lists:
|
|||
2. Numbered point two
|
||||
3. Numbered point three
|
||||
|
||||
## Blockquotes
|
||||
### Blockquotes
|
||||
|
||||
A blockquote will create an indented block. It's useful for emphasis and is
|
||||
added by starting one or more lines with `>`. For 'notes' you can also use
|
||||
|
|
@ -120,11 +120,11 @@ an explicit [Note](#note).
|
|||
> Note: This is an important
|
||||
> thing to remember.
|
||||
|
||||
## Links
|
||||
### Links
|
||||
|
||||
The link syntax is `[linktext](url_or_ref)` - this gives a clickable link [linktext](#links).
|
||||
|
||||
### Internal links
|
||||
#### 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
|
||||
|
|
@ -156,7 +156,7 @@ Some more text...
|
|||
> 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
|
||||
|
|
@ -169,7 +169,7 @@ resource under the `evennia/` repository:
|
|||
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.
|
||||
|
||||
### External links
|
||||
#### External links
|
||||
|
||||
These are links to resources outside of the documentation. We also provide some convenient shortcuts.
|
||||
|
||||
|
|
@ -202,7 +202,7 @@ 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:
|
||||
|
||||
|
|
@ -224,7 +224,7 @@ As seen, the Markdown syntax can be pretty sloppy (columns don't need to line up
|
|||
include the heading separators and make sure to add the correct number of `|` on every line.
|
||||
|
||||
|
||||
## Verbatim text
|
||||
### Verbatim text
|
||||
|
||||
It's common to want to mark something to be displayed verbatim - just as written - without any
|
||||
Markdown parsing. In running text, this is done using backticks (\`), like \`verbatim text\` becomes
|
||||
|
|
@ -330,7 +330,7 @@ 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
|
||||
|
|
@ -365,7 +365,7 @@ Also the important/warning notes indents like this.
|
|||
|
||||
```
|
||||
|
||||
### Important
|
||||
#### Important
|
||||
|
||||
This is for particularly important and visible notes.
|
||||
|
||||
|
|
@ -379,7 +379,7 @@ This is for particularly important and visible notes.
|
|||
This is important because it is!
|
||||
```
|
||||
|
||||
### Warning
|
||||
#### Warning
|
||||
|
||||
A warning block is used to draw attention to particularly dangerous things, or features easy to
|
||||
mess up.
|
||||
|
|
@ -394,7 +394,7 @@ mess up.
|
|||
Be careful about this ...
|
||||
```
|
||||
|
||||
### Version changes and deprecations
|
||||
#### Version changes and deprecations
|
||||
|
||||
These will show up as one-line warnings that suggest an added, changed or deprecated
|
||||
feature beginning with particular version.
|
||||
|
|
@ -425,7 +425,7 @@ feature beginning with particular version.
|
|||
```{deprecated} 1.0
|
||||
```
|
||||
|
||||
### Sidebar
|
||||
#### Sidebar
|
||||
|
||||
This will display an informative sidebar that floats to the side of regular content. This is useful
|
||||
for example to remind the reader of some concept relevant to the text.
|
||||
|
|
@ -461,7 +461,7 @@ squeezed to the left of the sidebar), one can embed a plain HTML string in the m
|
|||
|
||||
<div style="clear: right;"></div>
|
||||
|
||||
### A more flexible code block
|
||||
#### 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:`:
|
||||
|
|
@ -506,7 +506,7 @@ block through the link that will appear (so it should be unique for a given docu
|
|||
|
||||
|
||||
|
||||
### eval-rst directive
|
||||
#### eval-rst directive
|
||||
|
||||
As a last resort, we can also fall back to writing [ReST][ReST] directives directly:
|
||||
|
||||
|
|
@ -552,7 +552,7 @@ 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]
|
||||
extension to understand our friendly Google-style docstrings used in classes and functions etc.
|
||||
|
||||
# Building the docs locally
|
||||
## Building the docs locally
|
||||
|
||||
The sources in `evennia/docs/source/` are built into a documentation using the
|
||||
[Sphinx][sphinx] static generator system. To do this locally you need to use a
|
||||
|
|
@ -713,7 +713,6 @@ After deployment finishes, the updated live documentation will be
|
|||
available at https://evennia.github.io/evennia/latest/.
|
||||
|
||||
|
||||
|
||||
[sphinx]: https://www.sphinx-doc.org/en/master/
|
||||
[MyST]: https://myst-parser.readthedocs.io/en/latest/syntax/reference.html
|
||||
[commonmark]: https://spec.commonmark.org/current/
|
||||
|
|
@ -729,4 +728,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