From cb975f1b16284ccdc7ebcd8c345eb3b3bdc57eb1 Mon Sep 17 00:00:00 2001 From: Griatch Date: Sun, 5 Apr 2020 15:02:38 +0200 Subject: [PATCH] More fixes --- docs/Makefile | 36 +++++++++---- docs/README.md | 128 ++++++++++++++++++++++++++++++++++++++++++-- docs/source/conf.py | 14 +++-- 3 files changed, 161 insertions(+), 17 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 02681095d9..1298b162e9 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= +SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build SPHINXMULTIVERSION ?= sphinx-multiversion SPHINXAPIDOC ?= sphinx-apidoc @@ -14,16 +14,22 @@ AUTODOCDIR = $(SOURCEDIR)/api EVDIR ?= $(realpath ../evennia) EVGAMEDIR ?= $(realpath ../../gamedir) +cblue = $(shell echo "\033[1m\033[34m") +cnorm = $(shell echo "\033[0m") + +QUICKFILES=$(SOURCEDIR)/*.md + # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) @echo "Evennia-specific: " - @echo " install - get build requirements" - @echo " clean - remove remnants of a previous build" - @echo " local - build local html docs of the current branch (no multiversion)." - @echo " mv-local - build full multiversion html docs, without deploying (req. all changes committed to git)" - @echo " release - build and deploy multiversion docs online (req. github push access)" + @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)release$(cnorm) to build and deploy multiversion docs online (req. commit and github push access)" + .PHONY: help Makefile @@ -50,10 +56,13 @@ _multiversion-autodoc-index: git diff-index --quiet HEAD || git commit -a -m "Updated API autodoc index." _build: - @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" + @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" + +_quick-build: + NOAUTODOC=1 EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" $(QUICKFILES) _multiversion-build: - @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXMULTIVERSION) "$(SOURCEDIR)" "$(BUILDDIR)/html" + @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXMULTIVERSION) $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) _multiversion-deploy: @bash -e deploy.sh @@ -68,10 +77,16 @@ clean: @git clean -f -d docs/ @echo "Cleaned old build dir and leftover files." +quick: + make _check-env + make _quick-build $(FILES) + @echo "" + @echo "Documentation built (no autodocs). \nTo see result, open evennia/docs/build/html/index.html in a browser." + local: make _check-env make clean - make _autodoc_index + make _autodoc-index make _build @echo "" @echo "Documentation built. \nTo see result, open evennia/docs/build/html/index.html in a browser." @@ -83,6 +98,9 @@ mv-local: make _multiversion-build @echo "Documentation built. \nTo see result, open evennia/docs/build/html/versions//index.html in a browser." +deploy: + make _multiversion-deploy + # build and prepare the docs for release release: make mv-local diff --git a/docs/README.md b/docs/README.md index 6f7c9108ae..f70f4b990f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,7 @@ Documentation for the Evennia MUD creation system. The live documentation is available at `https://evennia.github.io/evennia/`. -# building the docs +# Building the docs ## Prerequisits @@ -19,9 +19,129 @@ a new game folder called `gamedir` at the same level as your `evennia` repo and ----- gamedir/ ``` -- Make sure you are in your virtualenv. Go to `evennia/docs/` and install the `requirements.txt` or run `make install` to do the same. +- Make sure you are in your virtualenv. Go to `evennia/docs/` and install the +`requirements.txt` or run `make install` to do the same. -## Building the docs. +## Building locally -With your build environment set up as above, stand in the `evennia/docs` directory and run `make local`. This builds the documentation. +With your build environment set up as above, stand in the `evennia/docs` directory and run + + make local + +This will build the html documentation (including api docs) in the new folder +`evennia/docs/build/html/`. To read it, open `evennia/docs/build/html/index.html` in any web browser. + +Building the api docs can be quite slow. If you are working on some doc change +and just want to quickly check that things came out the way you want, you can +also opt to only build the normal docs: + + make quick + +You will get errors from the api index and won't be able to view the api-docs, but it's +a lot faster to run! This will not clean out the `build/` dir between runs. If you +find you get any old stuff hanging around in the +`build/` dir you can use + + make clear + +to remove any old build cruft before next quick-build. + + +## Building for release + +The release-build will build all documentation branches. Only official Evennia +branches will be built so you can't use this to build your own testing branch. + +- All local changes must have been committed to git first, since the docs build +by looking at the git tree. +- To build for local checking, run + + make mv-local + +- Once all is built and it looks ok, run + + make deploy + +Note that this step requires git-push access to the Evennia `gh-pages` branch on `github`. + +If you know what you are doing you can also do + + make release + +This does the build + deploy steps automatically. + + +# Contributing and editing documentation + +Check out the branch of Evennia you want to edit the documentation for. Then make your own +branch off this, make your changes and make a PR for it! + +The documentation sources are in `evennia/docs/source/`. These are mainly +[Markdown][commonmark] (`.md`) files that you can edit like normal text files. +The ReST files in `source/api/` are auto-generated from the Evennia sources and +should _not_ be manually edited. + + +# Help with editing syntax + +## Referring to titles in another file + + +If file1 looks like this: + +``` +# Header title + +``` +You can refer to it from another file as + +``` +Read more about it [here](path.to.file1.md:Header title) + + +``` + +To refer to code in the Evennia repository, you can use a relative reference from the docs/ folder: + +``` +You can find this code [here](../evennia/objects/objects.py). + +``` + +This will be automatically translated to the matching github link so the reader can click and jump to that code directly. + + +## Making indices + +To make a document tree (what Sphinx refers to as a "Toc Tree"), make a list of document urls like this: + +``` +* [Title1](doc1.md) +* [Title2](doc2.md) + +``` + +This will create a toc-tree structure behind the scenes. + + + +We may expand on this later. For now, check out existing docs and refer to the +[Markdown][commonmark] (CommonMark) specification. + +# Technical + +Evennia leverages [Sphinx][sphinx] with the [recommonmark][recommonmark] extension, which allows us to write our +docs in light-weight Markdown (more specifically [CommonMark][commonmark], like on github) rather than ReST. +The recommonmark extension however also allows us to use ReST selectively in the places were it is more +expressive than the simpler (but much easier) Markdown. + +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. + + +[sphinx]: https://www.sphinx-doc.org/en/master/ +[recommonmark]: https://recommonmark.readthedocs.io/en/latest/index.html +[commonmark]: https://spec.commonmark.org/current/ +[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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 98ce0d3ec4..5ac688b4fb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -54,10 +54,17 @@ release = '0.9' # ones. extensions = [ "recommonmark", - "sphinx.ext.napoleon", - "sphinx_multiversion" + "sphinx_multiversion", + "sphinx.ext.autosectionlabel" ] +if not os.environ.get("NOAUTODOC"): + extensions.append("sphinx.ext.napoleon") + + +# 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'] @@ -95,8 +102,7 @@ smv_outputdir_format = "versions" + sep + "{config.release}" # dynamic setup -github_doc_root = "https://github.com/evennia/tree/master/docs/" - +github_doc_root = "https://github.com/evennia/tree/master/docs" def setup(app): # recommonmark setup