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

Copy doc tools from develop

Browse source
This commit is contained in:
Griatch 2020-07-12 20:01:44 +02:00
parent ca97c9bda0
commit c52f505d00
127 changed files with 2927 additions and 1427 deletions
Download patch file Download diff file Expand all files Collapse all files

67
docs/Makefile
View file

@ -1,5 +1,8 @@
# Makefile to control Evennia documentation building.
# Most common commands are `make help`, `make quick` and `make local`.
SOURCEDIR = source
BUILDDIR = build
AUTODOCDIR = $(SOURCEDIR)/api
# You can set these variables from the command line, and also
# from the environment for the first two.
@ -7,12 +10,9 @@ SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SPHINXMULTIVERSION ?= sphinx-multiversion
SPHINXAPIDOC ?= sphinx-apidoc
SPHINXAPIDOCOPTS = --tocfile evennia-api --module-first --force
SPHINXAPIDOCOPTS = --tocfile evennia-api --module-first --force -d 6 --separate --templatedir=$(SOURCEDIR)/_templates/
SPHINXAPIDOCENV = members,undoc-members,show-inheritance
SPHINXAPIDOCEXCLUDE = */migrations/*
SOURCEDIR = source
BUILDDIR = build
AUTODOCDIR = $(SOURCEDIR)/api
SPHINXAPIDOCEXCLUDE = ../*/migrations/* ../evennia/game_template/* ../evennia/*/tests/* ../evennia/*/tests.py
EVDIR ?= $(realpath ../evennia)
EVGAMEDIR ?= $(realpath ../../gamedir)
@ -20,7 +20,8 @@ EVGAMEDIR ?= $(realpath ../../gamedir)
cblue = $(shell echo "\033[1m\033[34m")
cnorm = $(shell echo "\033[0m")
QUICKFILES=$(SOURCEDIR)/*.md
# set specific files to only run for quick run (even if unset, will still not build new api docs)
QUICKFILES=
# Put it first so that "make" without argument is like "make help".
@ -30,9 +31,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
@ -55,17 +56,27 @@ _multiversion-check-env:
_clean_api_index:
rm source/api/*
# remove supervluous 'module' and 'package' text from api headers
_reformat_apidoc_headers:
for f in source/api/*.rst; do\
perl -pi -e 's/(module|package)$$// if $$. == 1' $$f ;\
done
_autodoc-index:
make _clean_api_index
@EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) SPHINX_APIDOC_OPTIONS=$(SPHINXAPIDOCENV) $(SPHINXAPIDOC) $(SPHINXAPIDOCOPTS) -o $(SOURCEDIR)/api/ $(EVDIR) $(SPHINXAPIDOCEXCLUDE)
make _reformat_apidoc_headers
_multiversion-autodoc-index:
make _clean_api_index
@EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) SPHINX_APIDOC_OPTIONS=$(SPHINXAPIDOCENV) $(SPHINXAPIDOC) $(SPHINXAPIDOCOPTS) -o $(SOURCEDIR)/api/ $(EVDIR) $(SPHINXAPIDOCEXCLUDE)
make _reformat_apidoc_headers
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 +84,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
@ -81,41 +96,47 @@ install:
clean:
@rm -Rf $(BUILDDIR)
@git clean -f -d docs/
# @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/<version>/index.html in a browser."
@echo ""
@echo "Documentation built (multiversion + autodocs)."
@echo "To see result, open evennia/docs/build/html/<version>/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."