Annikka/evennia
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Some more refactoring

Browse source
This commit is contained in:
Griatch 2020-06-16 09:33:41 +02:00
parent 748e658873
commit 97522f8f95
2 changed files with 104 additions and 106 deletions
Download patch file Download diff file Expand all files Collapse all files

201
docs/source/Contributing-Docs.md
View file

@ -1,47 +1,45 @@
# Evennia docs # Contributing to Evennia Docs
Documentation for the Evennia MUD creation system.
```warning:: ```warning::
WARNING: This system is still WIP and many things are bound to change! WARNING: This system is still WIP and many things are bound to change!
``` ```
The live documentation is (or will in the future be) available at Contributing to the docs is is like [contributing to the rest of Evennia][contributing]:
[https://evennia.github.io/evennia/latest](https://evennia.github.io/evennia/latest). Check out the branch of Evennia you want to edit the documentation for. Create your
own work-branch, make your changes to files in `evennia/docs/source/` and make a PR for it!
## Editing the docs
The documentation source files are `*.md` (Markdown) files found in `evennia/docs/source/`. 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 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 primarly use contain raw HTML directives (but that is very rarely needed). They primarly use
the [Markdown][commonmark] syntax. See [the syntax section below](#Editing-syntax) for more help. the [Markdown][commonmark] syntax. See [the syntax section below](#Editing-syntax) for more help.
> Note: Don't edit the files in `source/api/`. These are auto-generated and your changes > Note: Don't edit the files in `evennia/docs/source/api/`. These are auto-generated and your changes
> will be lost. > will be lost.
### Contributing to docs
Contributing to the docs is is like [contributing to the rest of Evennia][contributing]:
Check out the branch of Evennia you want to edit the documentation for. Create your
own work-branch, make your changes to files in `evennia/docs/source/` and make a PR for it!
## Building the docs locally ## Building the docs locally
The sources in `evennia/docs/source/` are built into a pretty documentation using The sources in `evennia/docs/source/` are built into a documentation using the
the [Sphinx][sphinx] static generator system. To do so locally you need to either [Sphinx][sphinx] static generator system. To do this locally you need to use a
use a system with `make` (Linux/Unix/Mac or [Windows-WSL][Windows-WSL]). Lacking that, you could system with `make` (Linux/Unix/Mac or [Windows-WSL][Windows-WSL]). Lacking
in principle also run the sphinx build-commands manually - read the `evennia/docs/Makefile` to see that, you could in principle also run the sphinx build-commands manually - read
which commands are run by `make`. the `evennia/docs/Makefile` to see which commands are run by the `make`-commands
referred to in this document.
You don't necessarily _have_ to build the docs locally to contribute. But You don't necessarily _have_ to build the docs locally to contribute. Markdown is
building them allows you to check for yourself that syntax is correct and that not hard and is very readable on its raw text-form.
your change comes out looking as you expected.
You can furthermore get a good feel for how things will look using a
Markdown-viewer like [Grip][grip]. Editors like [ReText][retext] or IDE's like
[PyCharm][pycharm] also have Markdown previews. Building the docs locally is
however the only way to make sure the outcome is exactly as you expect. The process
will also find any mistakes you made, like making a typo in a link.
### Building only the main documentation ### Building only the main documentation
If you only want to build the main documentation pages (not the API auto-docs), This is the fastest way to compile and view your changes. It will only build
you don't need to install Evennia itself, only the documentation resources. the main documentation pages and not the API auto-docs or versions. All is
All is done in your terminal/console. done in your terminal/console.
- (Optional, but recommended): Activate a virtualenv with Python 3.7. - (Optional, but recommended): Activate a virtualenv with Python 3.7.
- `cd` to into the `evennia/docs` folder. - `cd` to into the `evennia/docs` folder.
@ -53,16 +51,16 @@ All is done in your terminal/console.
pip install -r requirements.txt pip install -r requirements.txt
``` ```
- Next, build the html-based documentation: - Next, build the html-based documentation (re-run this in the future to build your changes):
``` ```
make quick make quick
``` ```
- Note any errors from files you have edited.
- The html-based documentation will appear in the new - The html-based documentation will appear in the new
folder `evennia/docs/build/html/`. Note any errors from files you have edited. folder `evennia/docs/build/html/`.
- Use a web browser to open `file://<path-to-folder>/evennia/docs/build/html/index.html` and view - Use a web browser to open `file://<path-to-folder>/evennia/docs/build/html/index.html` and view
the docs. Note that you will get errors if clicking a link to the auto-docs, because you didn't the docs. Note that you will get errors if clicking a link to the auto-docs, because you didn't
build them! build them!
### Building the main documentation and API docs ### Building the main documentation and API docs
@ -75,7 +73,7 @@ running)
- Follow the normal [Evennia Getting-Started instructions][getting-started] - Follow the normal [Evennia Getting-Started instructions][getting-started]
to install Evennia into a virtualenv. Get back here once everything is installed but to install Evennia into a virtualenv. Get back here once everything is installed but
before creating a new game. before creating a new game.
- Make sure you `cd` to the folder _containing_ your `evennia/` repo (so two levels - Make sure you `cd` to the folder _containing_ your `evennia/` repo (so two levels
up from `evennia/docs/`). up from `evennia/docs/`).
- Create a new game folder called exactly `gamedir` at the same level as your `evennia` - Create a new game folder called exactly `gamedir` at the same level as your `evennia`
repo with repo with
@ -101,7 +99,7 @@ repo with
----- gamedir/ ----- gamedir/
``` ```
If you are already working on a game, you may of course have your 'real' game folder there as If you are already working on a game, you may of course have your 'real' game folder there as
well. We won't touch that. well. We won't touch that.
- Make sure you are still in your virtualenv, then go to `evennia/docs/` and - Make sure you are still in your virtualenv, then go to `evennia/docs/` and
@ -121,7 +119,7 @@ well. We won't touch that.
- The rendered files will appear in a new folder `evennia/docs/build/html/`. - The rendered files will appear in a new folder `evennia/docs/build/html/`.
Note any errors from files you have edited. Note any errors from files you have edited.
- Point your web browser to `file://<path-to-folder>/evennia/docs/build/html/index.html` to - Point your web browser to `file://<path-to-folder>/evennia/docs/build/html/index.html` to
view the full docs. view the full docs.
#### Building with another gamedir #### Building with another gamedir
@ -152,10 +150,10 @@ docs are built by looking at the git tree.
``` ```
This is as close to the 'real' version as you can get locally. The different versions This is as close to the 'real' version as you can get locally. The different versions
will be found under `evennia/docs/build`. During deploy a symlink `latest` will point will be found under `evennia/docs/build`. During deploy a symlink `latest` will point
to the latest version of the docs. to the latest version of the docs.
#### Release #### Release
Releasing the official docs requires git-push access the the Evennia `gh-pages` branch Releasing the official docs requires git-push access the the Evennia `gh-pages` branch
on `github`. So there is no risk of you releasing your local changes accidentally. on `github`. So there is no risk of you releasing your local changes accidentally.
@ -178,29 +176,29 @@ available at https://evennia.github.io/evennia/latest/.
# Editing syntax # Editing syntax
The format used for Evennia's docs is [Markdown][commonmark-help] (Commonmark). While markdown supports a 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. 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: We generally use underscores for italics and double-asterisks for bold:
- `_Italic text_` - _Italic text_ - `_Italic text_` - _Italic text_
- `**Bold Text**` - **Bold 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 We use `#` to indicate sections/headings. The more `#` the more of a sub-heading it is (will get smaller
and smaller font). and smaller font).
- `# Heading` - `# Heading`
- `## SubHeading` - `## SubHeading`
- `## SubSubHeading` - `## SubSubHeading`
> Don't reuse the same heading/subheading name over and over in the same document. While Markdown does not prevent > Don't reuse the same heading/subheading name over and over in the same document. While Markdown does not prevent
it, it makes it impossible to link to those duplicates properly (see next section). it, it makes it impossible to link to those duplicates properly (see next section).
### Lists ### Lists
One can create both bullet-point lists and numbered lists: One can create both bullet-point lists and numbered lists:
@ -224,37 +222,37 @@ One can create both bullet-point lists and numbered lists:
2. Numbered point two 2. Numbered point two
3. Numbered point three 3. Numbered point three
### Notes ### Notes
A note can be used to enphasise important things. It's added by starting one or more lines with `>`. A note can be used to enphasise important things. It's added by starting one or more lines with `>`.
``` ```
> Note: This is an important > Note: This is an important
> thing to remember. > thing to remember.
``` ```
> Note: This is an important > Note: This is an important
> thing to remember. > thing to remember.
### Links ### Links
- `[linktext](url_or_ref)` - gives a clickable link [linktext][linkdemo]. - `[linktext](url_or_ref)` - gives a clickable link [linktext][linkdemo].
The `url_or_ref` can either be a full `http://...` url or an internal _reference_. For example, use The `url_or_ref` can either be a full `http://...` url or an internal _reference_. For example, use
`[my document](My-Document)` to link to the document `evennia/docs/source/My-Document.md`. Avoid using `[my document](My-Document)` to link to the document `evennia/docs/source/My-Document.md`. Avoid using
full `http://` linking unless really referring to an external resource. full `http://` linking unless really referring to an external resource.
- `[linktext](ref#heading-name)` - `[linktext](ref#heading-name)`
You can point to sub-sections (headings) in a document by using a single `#` and the name of the You can point to sub-sections (headings) in a document by using a single `#` and the name of the
heading, replacing spaces with dashes. So to refer to a heading `## Cool Stuff` inside `My-Document` heading, replacing spaces with dashes. So to refer to a heading `## Cool Stuff` inside `My-Document`
would be a link `[cool stuff](My-Document#Cool-Stuff)`. would be a link `[cool stuff](My-Document#Cool-Stuff)`.
- `[linktext][linkref]` - refer to a reference defined later in the document. - `[linktext][linkref]` - refer to a reference defined later in the document.
Urls can get long and if you are using the same url in many places it can get a little cluttered. So you can also put Urls can get long and if you are using the same url 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 the url as a 'footnote' at the end of your document
and refer to it by putting your reference within square brackets `[ ]`. Here's an example: and refer to it by putting your reference within square brackets `[ ]`. Here's an example:
``` ```
This is a [clickable link][mylink]. This is [another link][1]. This is a [clickable link][mylink]. This is [another link][1].
@ -267,7 +265,7 @@ This is a [clickable link][mylink]. This is [another link][1].
``` ```
#### Special references #### Special references
The Evennia documentation supports some special reference shortcuts in links: The Evennia documentation supports some special reference shortcuts in links:
@ -275,11 +273,11 @@ The Evennia documentation supports some special reference shortcuts in links:
- `github:` - a shortcut for the full path to the Evennia repository on github. This will refer to - `github:` - a shortcut for the full path to the Evennia repository on github. This will refer to
the `master` branch by default: the `master` branch by default:
[link to objects.py](github:evennia/objects/objects.py) [link to objects.py](github:evennia/objects/objects.py)
This will remap to https://github.com/evennia/evennia/blob/master/evennia/objects/objects.py. This will remap to https://github.com/evennia/evennia/blob/master/evennia/objects/objects.py.
- To refer to the `develop` branch, start the url with `develop/`: - To refer to the `develop` branch, start the url with `develop/`:
[link to objects.py](github:develop/evennia/objects/objects.py) [link to objects.py](github:develop/evennia/objects/objects.py)
@ -289,37 +287,37 @@ The Evennia documentation supports some special reference shortcuts in links:
[link to api for objects.py](api:evennia.objects) [link to api for objects.py](api:evennia.objects)
This will create a link to the auto-generated `evennia/source/api/evennia.objects.rst` document. This will create a link to the auto-generated `evennia/source/api/evennia.objects.rst` document.
Since api-docs are generated alongside the documentation, this will always be the api docs for the Since api-docs are generated alongside the documentation, this will always be the api docs for the
current version/branch of the docs. current version/branch of the docs.
##### Bug reports/feature request ##### Bug reports/feature request
- `issue`, `bug-report`, `feature-request` - links to the same github issue select page. - `issue`, `bug-report`, `feature-request` - links to the same github issue select page.
If you find a problem, make a [bug report](issue)! If you find a problem, make a [bug report](issue)!
This will generate a link to https://github.com/evennia/evennia/issues/new/choose. This will generate a link to https://github.com/evennia/evennia/issues/new/choose.
> For some reason these particular shortcuts gives a warning during documentation compilation. This > For some reason these particular shortcuts gives a warning during documentation compilation. This
> can be ignored. > can be ignored.
### Verbatim text ### Verbatim text
It's common to want to mark something to be displayed verbatim - just as written - without any 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 `verbatim text`. Markdown parsing. In running text, this is done using backticks (\`), like \`verbatim text\` becomes `verbatim text`.
If you want to put the verbatim text on its own line, you can do so easily by simply indenting If you want to put the verbatim text on its own line, you can do so easily by simply indenting
it 4 spaces (add empty lines on each side for readability too): it 4 spaces (add empty lines on each side for readability too):
``` ```
This is normal text This is normal text
This is verbatim text This is verbatim text
This is normal text This is normal text
``` ```
Another way is to use triple-backticks: Another way is to use triple-backticks:
@ -333,36 +331,36 @@ Everything within these backticks will be verbatim.
### Code blocks ### Code blocks
A special case is code examples - we want them to get code-highlighting for readability. This is done by using A special 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: the triple-backticks and specify which language we use:
```` ````
```python ```python
def a_python_func(x): def a_python_func(x):
return x * x return x * x
``` ```
```` ````
```python ```python
def a_python_func(x): def a_python_func(x):
return x * x return x * x
``` ```
### ReST blocks ### ReST blocks
Markdown is easy to read and use. But while it does most of what we need, there are some things it's 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 need to fall back to the [ReST][ReST] markup not quite as expressive as it needs to be. For this we need to fall back to the [ReST][ReST] markup
language which the documentation system uses under the hood. This is done by specifying `eval_rst` as language which the documentation system uses under the hood. This is done by specifying `eval_rst` as
the name of the `language` of a literal block: the name of the `language` of a literal block:
```` ````
```eval_rst ```eval_rst
This will be evaluated as ReST. This will be evaluated as ReST.
``` ```
```` ````
@ -370,7 +368,7 @@ There is also a short-hand form for starting a [ReST directive][ReST-directives]
```` ````
```directive:: possible-option ```directive:: possible-option
Content that *must* be indented for it to be included in the directive. Content that *must* be indented for it to be included in the directive.
New lines are ignored except if separated by an empty line. New lines are ignored except if separated by an empty line.
@ -399,36 +397,36 @@ feel more 'busy', so use with care.
#### Important #### Important
This is for particularly important and visible notes. This is for particularly important and visible notes.
```` ````
```important:: ```important::
This is important because it is! This is important because it is!
``` ```
```` ````
```important:: ```important::
This is important because it is! This is important because it is!
``` ```
#### Warning #### Warning
A warning block is used to draw attention to particularly dangerous things, or features easy to A warning block is used to draw attention to particularly dangerous things, or features easy to
mess up. mess up.
```` ````
```warning:: ```warning::
Be careful about this ... Be careful about this ...
``` ```
```` ````
```warning:: ```warning::
Be careful about this ... 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 These will show up as one-line warnings that suggest an added, changed or deprecated
feature beginning with particular version. feature beginning with particular version.
```` ````
@ -457,7 +455,7 @@ feature beginning with particular version.
```deprecated:: 1.0 ```deprecated:: 1.0
``` ```
#### Sidebar #### Sidebar
This will display an informative sidebar that floats to the side of regular content. This is useful 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. for example to remind the reader of some concept relevant to the text.
@ -469,8 +467,8 @@ for example to remind the reader of some concept relevant to the text.
- in here. - in here.
Headers: Headers:
with indented blocks like this with indented blocks like this
Will end up: Will end up:
as full sub-headings in the sidebar. as full sub-headings in the sidebar.
``` ```
```` ````
@ -481,15 +479,15 @@ for example to remind the reader of some concept relevant to the text.
- in here. - in here.
Headers: Headers:
with indented blocks like this with indented blocks like this
Will end up: Will end up:
as full sub-headings in the sidebar. as full sub-headings in the sidebar.
``` ```
Remember that for ReST-directives, the content within the triple-backticks _must_ be indented to Remember that for ReST-directives, the content within the triple-backticks _must_ be indented to
some degree or the content will just appear outside of the directive as regular text. some degree or the content will just appear outside of the directive as regular text.
If wanting to make sure to have the next header appear on a row of its own, one can embed If wanting to make sure to have the next header appear on a row of its own, one can embed
a plain HTML string in the markdown like so: a plain HTML string in the markdown like so:
```html ```html
<div style="clear: right;"></div> <div style="clear: right;"></div>
@ -497,7 +495,7 @@ a plain HTML string in the markdown like so:
<div style="clear: right;"></div> <div style="clear: right;"></div>
#### Tables #### Tables
A table is specified using [ReST table syntax][ReST-tables]: A table is specified using [ReST table syntax][ReST-tables]:
@ -553,9 +551,9 @@ or the more flexible but verbose
+------------------------+------------+----------+----------+ +------------------------+------------+----------+----------+
``` ```
#### A more flexible code block #### A more flexible code block
The regular Markdown codeblock is usually enough but for more direct control over the style, one The regular Markdown codeblock is usually enough but for more direct control over the style, one
can also specify the code block explicitly in `ReST`. can also specify the code block explicitly in `ReST`.
for more flexibility. It also provides a link to the code block, identified by its name. for more flexibility. It also provides a link to the code block, identified by its name.
@ -580,7 +578,7 @@ for more flexibility. It also provides a link to the code block, identified by i
```code-block:: python ```code-block:: python
:linenos: :linenos:
:emphasize-lines: 6-7,12 :emphasize-lines: 1-2,8
:caption: An example code block :caption: An example code block
:name: A full code block example :name: A full code block example
@ -595,9 +593,9 @@ for more flexibility. It also provides a link to the code block, identified by i
``` ```
Here, `:linenos:` turns on line-numbers and `:emphasize-lines:` allows for emphasizing certain lines Here, `:linenos:` turns on line-numbers and `:emphasize-lines:` allows for emphasizing certain lines
in a different color. The `:caption:` shows an instructive text and `:name:` is used to reference this in a different color. The `:caption:` shows an instructive text and `:name:` is used to reference this
block through the link that will appear (so it should be unique for a give document). block through the link that will appear (so it should be unique for a give document).
> The default markdown syntax will actually generate a code-block ReST instruction like this > The default markdown syntax will actually generate a code-block ReST instruction like this
> automatically for us behind the scenes. The automatic generation can't know things like emphasize-lines > automatically for us behind the scenes. The automatic generation can't know things like emphasize-lines
> or caption since that's not a part of the Markdown specification. > or caption since that's not a part of the Markdown specification.
@ -626,3 +624,6 @@ to understand our friendly Google-style docstrings used in classes and functions
[ReST-directives]: https://www.sphinx-doc.org/en/master/usage/restruturedtext/directives.html [ReST-directives]: https://www.sphinx-doc.org/en/master/usage/restruturedtext/directives.html
[Windows-WSL]: https://docs.microsoft.com/en-us/windows/wsl/install-win10 [Windows-WSL]: https://docs.microsoft.com/en-us/windows/wsl/install-win10
[linkdemo]: #Links [linkdemo]: #Links
[retext]: https://github.com/retext-project/retext
[grip]: https://github.com/joeyespo/grip
[pycharm]: https://www.jetbrains.com/pycharm/

9
docs/source/_static/nature.css
View file

@ -16,7 +16,7 @@
body { body {
font-family: Arial, sans-serif; font-family: Arial, sans-serif;
font-size: 100%; font-size: 100%;
background-color: #fff; background-color: #eee;
color: #555; color: #555;
margin: 0; margin: 0;
padding: 0; padding: 0;
@ -29,7 +29,6 @@ div.documentwrapper {
div.bodywrapper { div.bodywrapper {
margin: 0 0 0 230px; margin: 0 0 0 230px;
height: 88vh;
} }
hr { hr {
@ -46,7 +45,6 @@ div.body {
padding: 0 30px 30px 30px; padding: 0 30px 30px 30px;
font-size: 0.9em; font-size: 0.9em;
margin-top: -9px; margin-top: -9px;
height: 85vh;
} }
div.footer { div.footer {
@ -198,15 +196,14 @@ div.body h6 {
} }
a.headerlink { a.headerlink {
color: #cfdde8; color: #7caeb7;
font-size: 0.8em; font-size: 0.8em;
padding: 0 4px 0 4px; padding: 0 4px 0 4px;
text-decoration: none; text-decoration: none;
} }
a.headerlink:hover { a.headerlink:hover {
/*! background-color: #c60f0f; */ color: #7caeb7;
color: #9bced7;
} }
div.body p, div.body dd, div.body li { div.body p, div.body dd, div.body li {