diff --git a/docs/Makefile b/docs/Makefile index 09ce5533fe..43d5a32735 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -30,9 +30,9 @@ help: @echo " $(cblue)install$(cnorm) to get build requirements" @echo " $(cblue)clean$(cnorm) to remove remnants of a previous build" @echo " $(cblue)local$(cnorm) to build local html docs of the current branch (no multiversion)." - @echo " $(cblue)mv-local$(cnorm) to build multiversion html docs, without deploying (req. local git commit)" - @echo " $(cblue)deploy$(cnorm) to deploy previously built multiversion docs online (req. commit and github push access)" - @echo " $(cblue)release$(cnorm) to build + deploy multiversion docs online (req. commit and github push access)" + @echo " $(cblue)mv-local$(cnorm) to build multiversion html docs, without deploying (req: local git commit first)" + @echo " $(cblue)deploy$(cnorm) to deploy previously built multiversion docs online (req: commit and github push access)" + @echo " $(cblue)release$(cnorm) to build + deploy multiversion docs online (req: commit and github push access)" .PHONY: help Makefile @@ -62,10 +62,10 @@ _multiversion-autodoc-index: @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) SPHINX_APIDOC_OPTIONS=$(SPHINXAPIDOCENV) $(SPHINXAPIDOC) $(SPHINXAPIDOCOPTS) -o $(SOURCEDIR)/api/ $(EVDIR) $(SPHINXAPIDOCEXCLUDE) git diff-index --quiet HEAD || git commit -a -m "Updated API autodoc index." -_build: +_html-build: @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" -_quick-build: +_quick-html-build: @NOAUTODOC=1 EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" $(QUICKFILES) _multiversion-build: @@ -73,6 +73,10 @@ _multiversion-build: _multiversion-deploy: @bash -e deploy.sh + @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXMULTIVERSION) $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) + +_latex-build: + @NOAUTODOC=1 EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)/latex" $(QUICKFILES) # main targets @@ -84,38 +88,44 @@ clean: @git clean -f -d docs/ @echo "Cleaned old build dir and leftover files." -# TODO remove once done with migration -copy: - @cd pylib && python copy_from_wiki.py && cd .. - make quick +# not fully working at this time +pdf: + make _latex-build + @echo "" + @echo "Documentation built (single version, no autodocs)." + @echo "To see result, open evennia/docs/build/latex/evennia.pdf in a PDF reader." quick: make _check-env - make _quick-build $(FILES) + make _quick-html-build $(FILES) @echo "" - @echo "Documentation built (no autodocs). \nTo see result, open evennia/docs/build/html/index.html in a browser." + @echo "Documentation built (single version, no autodocs)." + @echo "To see result, open evennia/docs/build/html/index.html in a browser." local: make _check-env make clean make _autodoc-index - make _build + make _html-build @echo "" - @echo "Documentation built. \nTo see result, open evennia/docs/build/html/index.html in a browser." + @echo "Documentation built (single version)." + @echo "To see result, open evennia/docs/build/html/index.html in a browser." mv-local: make _multiversion-check-env make clean make _multiversion-autodoc-index make _multiversion-build - @echo "Documentation built. \nTo see result, open evennia/docs/build/html/versions//index.html in a browser." + @echo "" + @echo "Documentation built (multiversion + autodocs)." + @echo "To see result, open evennia/docs/build/html//index.html in a browser." deploy: make _multiversion-deploy + @echo "Documentation deployed." # build and prepare the docs for release release: make mv-local make deploy - @echo "" - @echo "Deployment complete." + @echo "Release complete." diff --git a/docs/README.md b/docs/README.md index 4e9676cfaf..4912dc921e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,5 @@ -# evennia-docs +# Evennia docs + Documentation for the Evennia MUD creation system. > WARNING: This system is still WIP and many things are bound to change! @@ -9,26 +10,25 @@ The live documentation is (will in the future be) available at `https://evennia. # Editing the docs 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 use -the [Markdown][commonmark] syntax. +Markdown files are simple text files that can be edited with a normal text editor. They primaroly use +the [Markdown][commonmark] syntax. See [the syntax section below](#Editing-syntax) for more help. Don't edit the files in `source/api/`. These are auto-generated and your changes will be lost. -See also later in this doc for [Help with editing syntax](#Help-with-editing-syntax). - ## Contributing 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 and make a PR for it! +own work-branch, make your changes to files in `evennia/docs/source/` and make a PR for it! -# Building the docs +# Building the docs locally The sources in `evennia/docs/source/` are built into a pretty documentation using the [Sphinx][sphinx] static generator system. To do so locally you need to either -use a system with `make` (Linux/Unix/Mac/Windows-WSL) or run sphinx-commands manually -(read the `Makefile` to see which commands are run by `make`). +use a system with `make` (Linux/Unix/Mac or [Windows-WSL][Windows-WSL]). Lacking that, you could +in principle also run the sphinx build-commands manually - read the `evennia/docs/Makefile` to see +which commands are run by `make`. You don't necessarily _have_ to build the docs locally to contribute. But building them allows you to check for yourself that syntax is correct and that @@ -159,72 +159,316 @@ can now deploy. - After deployment finishes, the updated live documentation will be available at `https://evennia.github.io/evennia/`. -# Help with editing syntax +# Editing syntax -> This needs expanding in the future. +The format 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. -## Referring to a heading in the same file +## Italic/Bold -You can self-reference by pointing to a header/label elsewhere in the -same document by using `#` and replacing any spaces in the name with `-`. +We generally use underscores for italics and double-asterisks for bold: + +- `_Italic text_` +- `**Bold Text**` + +## Headings + +We use `#` to indicate sections/headings. The more `#` the more of a sub-heading it is (will get smaller +and smaller font). + +- `# Heading` +- `## SubHeading` +- `## SubSubHeading` + +> 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). + +## Lists + +One can create both bullet-point lists and numbered lists: + +```markdown +- first bulletpoint +- second bulletpoint +- third bulletpoint +``` +```markdown +1. Numbered point one +2. Numbered point two +3. Numbered point three +``` + +## Notes + +A note can be used to enphasise important things. It's added by starting one or more lines with `>`. ``` -This is a [link to the heading](#My-Heading-Name). +> Note: This is an important +> thing to remember. +``` -# My Heading Name +## Links + +- `[linktext](url_or_ref)` - gives a clickable link `linktext`. + +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 +full `http://` linking unless really referring to an external resource. + +- `[linktext](ref#heading-name)` + +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` +would be a link `[cool stuff](My-Document#Cool-Stuff)`. + +- `[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 +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: + +``` +This is a [clickable link][mylink]. This is [another link][1]. + +... + + +[mylink]: http://... +[1]: My-Document ``` -## Referring to titles in another file +### Special references -> WIP: Most of these special structures need more work and checking. +The Evennia documentation supports some special reference shortcuts in links: -If file1 looks like this: +#### Github online repository + +- `github:` - a shortcut for the full path to the Evennia repository on github. This will refer to + the `master` branch by default: + + [link to objects.py](github: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/`: + + [link to objects.py](github:develop/evennia/objects/objects.py) + +#### API + +- `api:` - references a path in the api documentation. This is specified as a Python-path: + + [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. + + Since api-docs are generated alongside the documentation, this will always be the api docs for the + current version/branch of the docs. + +#### Bug reports/feature request + + +- `issue`, `bug-report`, `feature-request` - links to the same github issue select page. + + If you find a problem, make a [bug report](issue)! + + 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 + > can be ignored. + +## 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 `verbatim text`. + +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): ``` -# Header title +This is normal text + This is verbatim text + +This is normal text ``` -You can refer to it from another file as +Another way is to use triple-backticks: + +```` +``` +Everything within these backticks will be verbatim. ``` -Read more about it [here](path.to.file1.md:Header title) +```` +## Code blocks + +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: + +```` +```python + +def a_python_func(x): + return x * x + +``` +```` + +## ReST blocks + +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 +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: + +```` +```eval_rst + + This will be evaluated as ReST. ``` -> This is not actually working at this time (WIP) +```` +There is also a short-hand form for starting a [ReST directive][ReST-directives] without need for `eval_rst`: -To refer to code in the Evennia repository, you can use a relative reference from the docs/ folder: +```` +```directive:: possible-option + + Content that *must* be indented for it to be included in the directive. + New lines are ignored except if separated by an empty line. ``` -You can find this code [here](../evennia/objects/objects.py). +```` +See below for examples of this. + +#### Important + +This will display a one-line note that will pop even more than a normal `> note`. + +```` +```important:: + This is important because it is! ``` -This will be automatically translated to the matching github link so the reader can click and jump to that code directly. -> This is not currently working. (WIP) +```` +#### Warning -## Making toc-tree indices +A warning block is used to draw attention to particularly dangerous things, or features easy to +mess up. -To make a Table-of-Contents listing (what Sphinx refers to as a "Toc Tree"), one -must make new heading named either `Contents` or `Index`, followed by a bullet-list of -links: +```` +```warning:: + Be careful about this ... +```` +#### Version changes and deprecations + +These will show up as one-line warnings that suggest an added, changed or deprecated +feature beginning with particular version. + +```` +```versionadded:: 1.0 ``` -# Index - -- [Title1](doc1) -- [Title2](doc2) +```` +```` +```versionchanged:: 1.0 + How the feature changed with this version. ``` - -This will create a toc-tree structure behind the scenes. +```` +```` +```deprecated:: 1.0 +``` +```` +#### Sidebar -We may expand on this later. For now, check out existing docs and refer to the -[Markdown][commonmark] (CommonMark) specification. +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. + +```` +```sidebar:: Things to remember + + - There can be bullet lists + - in here. + + Headers with indented blocks: + like this + Will end up as full sub-headings: + in the sidebar. +``` +```` + +> 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. + +#### Tables + +A table is specified using [ReST table syntax][ReST-tables]: + +```` +```eval_rst + +===== ===== ======= +A B A and B +===== ===== ======= +False False False +True False False +False True False +True True True +===== ===== ======= +``` +```` + +or the more flexible but verbose + +```` +```eval_rst ++------------------------+------------+----------+----------+ +| Header row, column 3 | Header 2 | Header 3 | Header 4 | +| (header rows optional) | | | | ++========================+============+==========+==========+ +| body row 1, column 1 | column 2 | column 3 | column 4 | ++------------------------+------------+----------+----------+ +| body row 2 | ... | ... | | ++------------------------+------------+----------+----------+ +``` +```` + +#### A more flexible code block + +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`. +for more flexibility. It also provides a link to the code block, identified by its name. + + +```` +```code-block:: python + :linenos: + :emphasize-lines: 6-7,12 + :caption: An example code block + :name: A full code block example + + from evennia import Command + class CmdEcho(Command): + """ + Usage: echo + """ + key = "echo" + def func(self): + self.caller.msg(self.args.strip()) +``` +```` +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 +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 +> 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. # Technical @@ -237,11 +481,16 @@ For [autodoc-generation][sphinx-autodoc] generation, we use the sphinx-[napoleon to understand our friendly Google-style docstrings used in classes and functions etc. + [sphinx]: https://www.sphinx-doc.org/en/master/ [recommonmark]: https://recommonmark.readthedocs.io/en/latest/index.html [commonmark]: https://spec.commonmark.org/current/ +[commonmark-help]: https://commonmark.org/help/ [sphinx-autodoc]: http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc [sphinx-napoleon]: http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html [getting-started]: https://github.com/evennia/evennia/wiki/Getting-Started [contributing]: https://github.com/evennia/evennia/wiki/Contributing - +[ReST]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +[ReST-tables]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables +[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 diff --git a/docs/source/api/evennia.contrib.awsstorage.rst b/docs/source/api/evennia.contrib.awsstorage.rst new file mode 100644 index 0000000000..864d562817 --- /dev/null +++ b/docs/source/api/evennia.contrib.awsstorage.rst @@ -0,0 +1,27 @@ +evennia.contrib.awsstorage package +================================== + +.. automodule:: evennia.contrib.awsstorage + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +evennia.contrib.awsstorage.aws\_s3\_cdn module +---------------------------------------------- + +.. automodule:: evennia.contrib.awsstorage.aws_s3_cdn + :members: + :undoc-members: + :show-inheritance: + +evennia.contrib.awsstorage.tests module +--------------------------------------- + +.. automodule:: evennia.contrib.awsstorage.tests + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/source/api/evennia.web.api.rst b/docs/source/api/evennia.web.api.rst new file mode 100644 index 0000000000..fb31841818 --- /dev/null +++ b/docs/source/api/evennia.web.api.rst @@ -0,0 +1,59 @@ +evennia.web.api package +======================= + +.. automodule:: evennia.web.api + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +evennia.web.api.filters module +------------------------------ + +.. automodule:: evennia.web.api.filters + :members: + :undoc-members: + :show-inheritance: + +evennia.web.api.permissions module +---------------------------------- + +.. automodule:: evennia.web.api.permissions + :members: + :undoc-members: + :show-inheritance: + +evennia.web.api.serializers module +---------------------------------- + +.. automodule:: evennia.web.api.serializers + :members: + :undoc-members: + :show-inheritance: + +evennia.web.api.tests module +---------------------------- + +.. automodule:: evennia.web.api.tests + :members: + :undoc-members: + :show-inheritance: + +evennia.web.api.urls module +--------------------------- + +.. automodule:: evennia.web.api.urls + :members: + :undoc-members: + :show-inheritance: + +evennia.web.api.views module +---------------------------- + +.. automodule:: evennia.web.api.views + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/source/conf.py b/docs/source/conf.py index d56403b4cc..001ac64bc9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -35,6 +35,9 @@ extensions = [ "sphinx.ext.githubpages", ] +source_suffix = ['.md', '.rst'] +master_doc = 'index' + # make sure sectionlabel references can be used as path/to/file:heading autosectionlabel_prefix_document = True @@ -58,9 +61,9 @@ smv_tag_whitelist = r"^$" # -- Options for HTML output ------------------------------------------------- -html_theme = "alabaster" -# html_theme = "standford_theme" -# html_theme_path = [sphinx_theme.get_html_theme_path("stanford_theme")] +# html_theme = "alabaster" +html_theme = "stanford_theme" +html_theme_path = [sphinx_theme.get_html_theme_path("stanford_theme")] # Custom extras for sidebar html_sidebars = { @@ -79,27 +82,53 @@ html_favicon = "_static/favicon.ico" pygments_style = "sphinx" +# -- Options for LaTeX output ------------------------------------------------ +# experimental, not working well atm + +latex_engine = 'xelatex' +latex_show_urls = 'footnote' +latex_elements = { + 'papersize': 'a4paper', + 'fncychap': r'\usepackage[Bjarne]{fncychap}', + 'fontpkg': r'\usepackage{times,amsmath,amsfonts,amssymb,amsthm}', + 'preamble': r''' + \usepackage[utf8]{fontenc} + \usepackage{amsmath,amsfonts,amssymb,amsthm} + \usepackage[math-style=literal]{unicode-math} + \usepackage{newunicodechar} + \usepackage{graphicx} + ''' +} +latex_documents = [ + (master_doc, 'main.tex', 'Sphinx format', 'Evennia', 'report'), + ("toc", 'toc.tex', 'TOC', 'Evennia', 'report') +] + + # -- Recommonmark ------------------------------------------------------------ # allows for writing Markdown and convert to rst dynamically # reroute to github links or to the api -_github_code_root = "https://github.com/evennia/evennia/blob/master/" +_github_code_root = "https://github.com/evennia/evennia/blob/" _github_doc_root = "https://github.com/evennia/tree/master/docs/sources/" _github_issue_choose = "https://github.com/evennia/evennia/issues/new/choose" def url_resolver(url): - urlstart = "github:" + githubstart = "github:" apistart = "api:" - choose_issue = ("feature-request", "report-bug", "issue") + choose_issue = ("feature-request", "report-bug", "issue", "bug-report") if url.lower().strip() in choose_issue: return _github_issue_choose - elif url.startswith(urlstart): - return _github_code_root + url[len(urlstart) :] + + elif url.startswith(githubstart): + urlpath = url[len(githubstart):] + if not (urlpath.startswith("develop/") or urlpath.startswith("master")): + urlpath = "master/" + urlpath + return _github_code_root + urlpath elif url.startswith(apistart): - print("api: -> api ref") return "api/" + url[len(apistart) :] + ".html" return url # else: diff --git a/docs/source/index.md b/docs/source/index.md index 1f9823b5a2..331f595a58 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -9,10 +9,81 @@ > For now you are best off using the original wiki, or the less changing v0.9.1 > of these docs. You have been warned. +```sidebar:: An important sidebar + + - Extra features + - Another feature + + Third feature: + Stuff to do + + Fourth feature: + Even more. +``` + # Evennia Documentation This is the manual of [Evennia](http://www.evennia.com), the open source Python -`MU*` creation system. +`MU*` creation system. A link to the [feature-request](issue) + +```note:: + + This is a particular note. + +```warning:: This is an important thing! + Especially this. +``` + +```important:: This is an interesting thing! + + More text here! + + And here. +``` + +```seealso:: This is good to look at too. + This in particular +``` + +```versionadded:: 1.0 + + This feature was added here + +``` + +```deprecated:: 1.0 + Use this thing instead. +``` + +```code-block:: python + :emphasize-lines: 6-7,12 + :caption: An example code-block with everything turned on. + :name: Full code-block example + + # Comment line + from evennia import Command + + class MyCommand(Command): + """ + Usage: + cmd x + """ + key = "cmd" + + def func(self): + self.caller.msg(self.args) +``` + +```markdown + # Comment line + import System + System.run_emphasis_line + # Long lines in code blocks create a auto horizontal scrollbar + System.exit! + +``` + +
There is [a lengthier introduction](Evennia-Introduction) to read. You might also want to read about [how to get and give help](How-To-Get-And-Give-Help).