mirror of
https://github.com/evennia/evennia.git
synced 2026-03-16 21:06:30 +01:00
More fixes
This commit is contained in:
Griatch
parent
9f7d826957
commit
cb975f1b16
3 changed files with 161 additions and 17 deletions
|
|
@ -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/<version>/index.html in a browser."
|
||||
|
||||
deploy:
|
||||
make _multiversion-deploy
|
||||
|
||||
# build and prepare the docs for release
|
||||
release:
|
||||
make mv-local
|
||||
|
|
|
|||
128
docs/README.md
128
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue