From 2a79f623c48e7611b98d3372a6ea2ee29b41e782 Mon Sep 17 00:00:00 2001 From: Griatch Date: Sun, 14 Jun 2020 20:20:43 +0200 Subject: [PATCH] Back-port some config/readme from develop --- docs/README.md | 329 ++++++++++++++++++++++++++++++++++++++------ docs/source/conf.py | 295 ++++++++++++++++++++++----------------- 2 files changed, 456 insertions(+), 168 deletions(-) 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/conf.py b/docs/source/conf.py index 5d664d5541..fc8e4ad411 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -6,11 +6,149 @@ import os import sys -from os.path import sep +import sphinx_theme from recommonmark.transform import AutoStructify from sphinx.util.osutil import cd +# -- Project information ----------------------------------------------------- + +project = "Evennia" +copyright = "2020, The Evennia developer community" +author = "The Evennia developer community" + +# The full Evennia version covered by these docs, including alpha/beta/rc tags +# This will be used for multi-version selection options. +release = "0.9.1" + + +# -- General configuration --------------------------------------------------- + +extensions = [ + "recommonmark", + "sphinx_multiversion", + "sphinx.ext.napoleon", + "sphinx.ext.autosectionlabel", + "sphinx.ext.viewcode", + # "sphinxcontrib.lunrsearch", + "sphinx.ext.todo", + "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 + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + + +# -- Sphinx-multiversion config ---------------------------------------------- + +# which branches to include in multi-versioned docs +# - master, develop and vX.X branches +smv_branch_whitelist = r"^master$|^develop$|^v[0-9\.]+?$" +smv_outputdir_format = "{config.release}" +# don't make docs for tags +smv_tag_whitelist = r"^$" + + +# -- Options for HTML output ------------------------------------------------- + +# html_theme = "alabaster" +html_theme = "stanford_theme" +html_theme_path = [sphinx_theme.get_html_theme_path("stanford_theme")] + +# Custom extras for sidebar +html_sidebars = { + "**": [ + "searchbox.html", + "localtoc.html", + # "globaltoc.html", + "relations.html", + "sourcelink.html", + "versioning.html", + ] +} +html_favicon = "_static/favicon.ico" + +# HTML syntax highlighting style +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/" +_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): + githubstart = "github:" + apistart = "api:" + choose_issue = ("feature-request", "report-bug", "issue", "bug-report") + + if url.lower().strip() in choose_issue: + return _github_issue_choose + + 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): + return "api/" + url[len(apistart) :] + ".html" + return url + # else: + # return _github_doc_root + url + + +# auto-create TOCs if a list of links is under these headers +auto_toc_sections = ["Contents", "Toc", "Index"] + +recommonmark_config = { + "enable_auto_toc_tree": True, + "url_resolver": url_resolver, + "auto_toc_tree_section": ["Contents", "Toc", "Index"], + "code_highlight_options": {"force": True, "linenos": True}, +} + + +# -- API/Autodoc --------------------------------------------------------------- +# automatic creation of API documentation. This requires a valid Evennia setup + _no_autodoc = os.environ.get("NOAUTODOC") if not _no_autodoc: @@ -20,9 +158,11 @@ if not _no_autodoc: GAME_DIR = os.environ.get("EVGAMEDIR") if not (EV_ROOT and GAME_DIR): - err = ("The EVDIR and EVGAMEDIR environment variables must be set to " - "the absolute paths to the evennia/ repo and an initialized " - "evennia gamedir respectively.") + err = ( + "The EVDIR and EVGAMEDIR environment variables must be set to " + "the absolute paths to the evennia/ repo and an initialized " + "evennia gamedir respectively." + ) raise RuntimeError(err) print("Evennia root: {}, Game dir: {}".format(EV_ROOT, GAME_DIR)) @@ -35,60 +175,36 @@ if not _no_autodoc: os.environ["DJANGO_SETTINGS_MODULE"] = "server.conf.settings" import django # noqa + django.setup() import evennia # noqa + evennia._init() +if _no_autodoc: + exclude_patterns = ["api/*"] +else: + exclude_patterns = ["api/*migrations.rst"] -# -- Project information ----------------------------------------------------- - -project = 'Evennia' -copyright = '2020, The Evennia developer community' -author = 'The Evennia developer community' - -# The full version, including alpha/beta/rc tags -release = '0.9.1' - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "recommonmark", - "sphinx_multiversion", - "sphinx.ext.napoleon", - "sphinx.ext.autosectionlabel", - "sphinx.ext.viewcode", - # "sphinxcontrib.lunrsearch", -] - -# make sure sectionlabel references can be used as path/to/file:heading -autosectionlabel_prefix_document = True - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Custom extras for sidebar -html_sidebars = { - '**': [ - "searchbox.html", - "localtoc.html", - # "globaltoc.html", - "relations.html", - "sourcelink.html", - "versioning.html", - ] +autodoc_default_options = { + "members": True, + "undoc-members": True, + "show-inheritance": True, + "special-members": "__init__", + "enable_eval_rst": True, } -html_favicon = "_static/favicon.ico" -# napoleon Google-style docstring parser +def autodoc_skip_member(app, what, name, obj, skip, options): + if _no_autodoc: + return True + if name.startswith("__") and name != "__init__": + return True + return False + + +# Napoleon Google-style docstring parser for autodocs napoleon_google_docstring = True napoleon_numpy_docstring = False @@ -104,85 +220,8 @@ napoleon_use_keyword = True napoleon_use_rtype = True -# settings for sphinxcontrib.apidoc to auto-run sphinx-apidocs - -if _no_autodoc: - exclude_patterns = ["api/*"] -else: - exclude_patterns = ["api/*migrations.rst"] - -# for inline autodoc - -autodoc_default_options = { - "members": True, - "undoc-members": True, - "show-inheritance": True, - "special-members": "__init__", - "enable_eval_rst": True, -} - -def autodoc_skip_member(app, what, name, obj, skip, options): - if _no_autodoc: - return True - if name.startswith("__") and name != "__init__": - return True - return False - - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'alabaster' - - -# sphinx-multiversion config - -smv_tag_whitelist = r"^$" -# which branches to include in multi-version docs -# - master, develop and vX.X branches -smv_branch_whitelist = r"^master$|^develop$|^v[0-9\.]+?$" -smv_outputdir_format = "{config.release}" - - -# recommonmark - -# reroute to github links or to the api - -_github_code_root = "https://github.com/evennia/evennia/blob/master/" -_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:" - apistart = "api:" - choose_issue = ("feature-request", "report-bug", "issue") - - 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(apistart): - print("api: -> api ref") - return "api/" + url[len(apistart):] + ".html" - return url - # else: - # return _github_doc_root + url - - -# auto-create TOCs if a list of links is under these headers -auto_toc_sections = ["Contents", "Toc", "Index"] - -recommonmark_config = { - "enable_auto_toc_tree": True, - "url_resolver": url_resolver, - "auto_toc_tree_section": ["Contents", "Toc", "Index"], - "code_highlight_options": {"force": True, - "linenos": True} -} +# -- Main config setup ------------------------------------------ +# last setup steps for some plugins def setup(app):