From f5bf1d6545eeba516fd177e2baa5415a54bd84a9 Mon Sep 17 00:00:00 2001 From: Griatch Date: Sun, 5 Apr 2020 00:02:02 +0200 Subject: [PATCH] Add docs/ dir --- docs/LICENSE | 29 +++++++ docs/Makefile | 69 ++++++++++++++++ docs/README.md | 6 ++ docs/checkenv.sh | 24 ++++++ docs/deploy.sh | 26 ++++++ docs/make.bat | 35 +++++++++ docs/pylib/copy_from_wiki.py | 100 +++++++++++++++++++++++ docs/requirements.txt | 7 ++ docs/source/_static/.empty.txt | 0 docs/source/_templates/versioning.html | 8 ++ docs/source/conf.py | 105 +++++++++++++++++++++++++ docs/source/index.md | 10 +++ docs/source/index.rst | 20 +++++ 13 files changed, 439 insertions(+) create mode 100644 docs/LICENSE create mode 100644 docs/Makefile create mode 100644 docs/README.md create mode 100644 docs/checkenv.sh create mode 100644 docs/deploy.sh create mode 100644 docs/make.bat create mode 100644 docs/pylib/copy_from_wiki.py create mode 100644 docs/requirements.txt create mode 100644 docs/source/_static/.empty.txt create mode 100644 docs/source/_templates/versioning.html create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.md create mode 100644 docs/source/index.rst diff --git a/docs/LICENSE b/docs/LICENSE new file mode 100644 index 0000000000..29f8f5aca2 --- /dev/null +++ b/docs/LICENSE @@ -0,0 +1,29 @@ +BSD 3-Clause License + +Copyright (c) 2019, evennia +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..4a965466e5 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,69 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +EVDIR ?= $(realpath ../) +EVGAMEDIR ?= $(realpath ../../gamedir) + + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo "Evennia-specific: " + @echo " release - build and prepare multiversion docs and auto-docs for release." + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + make help + # @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +# Evennia - custom commands + +install: + @pip install -r requirements.txt + +check-env: + @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) bash -e checkenv.sh + +# build only the api-autodoc index +autodoc-index: + @sphinx-apidoc -f -o $(SOURCEDIR)/api/ $(EVDIR) + +api-build: + @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) $(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html/api" + +multiversion-build: + @EVDIR=$(EVDIR) EVGAMEDIR=$(EVGAMEDIR) sphinx-multiversion "$(SOURCEDIR)" "$(BUILDDIR)/html" + +clean: + @rm -Rf $(BUILDDIR) + @git clean -f -d + @echo "Cleaned old build dir and leftover files." + +local: + make check-env + make autodoc-index + make multiversion-build + +deploy: + @bash -e deploy.sh + +# build and prepare the docs for release +release: + make check-env + make clean + make autodoc-index + make multiversion-build + make deploy + make clean + @echo "" + @echo "Deployment complete." diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..45bb89e551 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,6 @@ +# evennia-docs +Documentation for the Evennia MUD creation system. + +This is very much WIP. We are still experimenting with solutions. Don't use or contribute yet. + +The live documentation will be available at `https://evennia.github.io/evennia-docs`. diff --git a/docs/checkenv.sh b/docs/checkenv.sh new file mode 100644 index 0000000000..42ceb6bc12 --- /dev/null +++ b/docs/checkenv.sh @@ -0,0 +1,24 @@ + +# check environment + + +# if [ -n "$(git status --untracked-files=no --porcelain)" ]; then +# echo "There are uncommitted changes. Make sure to commit everything in your current branch first." +# exit 1 +# fi + +if [ ! -d "$EVDIR" ]; then + + echo "The evennia dir is not found at $EVDIR."; + exit 1 +else + echo "Evennia dir correctly set to $EVDIR."; +fi + +if [ ! -d "$EVGAMEDIR" ]; then + + echo "The gamedir is not found at $EVGAMEDIR"; + exit 1 +else + echo "Evennia game dir correctly set to $EVGAMEDIR."; +fi diff --git a/docs/deploy.sh b/docs/deploy.sh new file mode 100644 index 0000000000..05712c8111 --- /dev/null +++ b/docs/deploy.sh @@ -0,0 +1,26 @@ +# +# deploy to github +# +# This copies the recently built files from build/html into the github-gh branch. Note that +# it's important that build/ must not be committed to git! +# + +if [ -n "$(git status --untracked-files=no --porcelain)" ]; then + echo "There are uncommitted changes. Make sure to commit everything in your current branch first." + exit 1 +fi + +git checkout gh-pages + +rm -Rf versions +mv build/html/versions . +git add versions + +git commit -a -m "Updated HTML docs" +git push origin gh-pages + +# get back to previous branch + + git checkout - + +echo "Deployed to https://evennia.github.io/evennia-docs." diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000..6247f7e231 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/pylib/copy_from_wiki.py b/docs/pylib/copy_from_wiki.py new file mode 100644 index 0000000000..8a0cc98a59 --- /dev/null +++ b/docs/pylib/copy_from_wiki.py @@ -0,0 +1,100 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- + +""" +Prepare files for mkdoc. This assumes evennia.wiki is cloned +to a folder at the same level as the evennia-docs repo. + +Just run this to update everything. + +""" + +import glob +import re + +_RE_MD_LINK = re.compile(r"\[(?P[\w -]+)\]\((?P\w+?)\)", re.I + re.S + re.U) + +_WIKI_DIR = "../../evennia.wiki/" +_INFILES = sorted(glob.glob(_WIKI_DIR + "/*.md")) +_FILENAMES = [path.rsplit("/", 1)[-1] for path in _INFILES] +_FILENAMESLOW = [path.lower() for path in _FILENAMES] +_OUTDIR = "../sources/" + +_CUSTOM_LINK_REMAP = { + "CmdSets.md": "Command-Sets.md", + "CmdSet.md": "Command-Sets.md", + "Cmdsets.md": "Command-Sets.md", + "CommandSet.md": "Command-Sets.md", + "batch-code-processor.md": "Batch-Code-Processor.md", + "Batch-code-processor.md": "Batch-Code-Processor.md", + "batch-command-processor.md": "Batch-Command-Processor.md", + "Batch-command-processor.md": "Batch-Command-Processor.md", + "evennia-API.md": "Evennia-API.md", + "Win.md": "Win", + "Mac.md": "Mac", + "IOS.md": "IOS", + "Andr.md": "Andr", + "Unix.md": "Unix", + "Chrome.md": "Chrome", + "EvTable.md": "EvTable.md", + "Channels.md": "Communications.md#Channels", + "Comms.md": "Communications.md", + "typeclass.md": "Typeclasses.md", + "Home.md": "index.md" +} + + +def _sub_link(match): + mdict = match.groupdict() + txt, url = mdict['txt'], mdict['url'] + if not txt: + # the 'comment' is not supported by Mkdocs + return "" + url = url if url.endswith(".md") or url.startswith("http") else url + ".md" + + print("url:", url) + url = _CUSTOM_LINK_REMAP.get(url, url) + + if url not in _FILENAMES and not url.startswith("http") and "#" not in url: + url_cap = url.capitalize() + url_plur = url[:-3] + 's' + ".md" + url_cap_plur = url_plur.capitalize() + + print(f"Link [{txt}]({url}) has no matching target") + if url_cap in _FILENAMES: + print(f" Replacing (capitalized): {url.capitalize()}") + return url_cap + if url_plur in _FILENAMES: + print(f" Replacing (pluralized): {url + 's'}") + return url_plur + if url_cap_plur in _FILENAMES: + print(f" Replacing (capitalized, pluralized): {url.capitalize() + 's'}") + return url_cap_plur + if url.lower() in _FILENAMESLOW: + ind = _FILENAMESLOW.index(url.lower()) + alt = _FILENAMES[ind] + print(f" Possible match (different cap): {alt}") + inp = input("Enter alternate url (return to keep old): ") + if inp.strip(): + url = inp.strip() + + return f"[{txt}]({url})" + + +for inpath in _INFILES: + print(f"Converting links in {inpath} ->", end=" ") + with open(inpath) as fil: + text = fil.read() + text = _RE_MD_LINK.sub(_sub_link, text) + text = text.split('\n')[1:] if text.split('\n')[0].strip().startswith('[]') else text.split('\n') + text = '\n'.join(text) + + outfile = inpath.rsplit('/', 1)[-1] + if outfile == "Home.md": + outfile = "index.md" + outfile = _OUTDIR + outfile + + with open(outfile, 'w') as fil: + fil.write(text) + + print(f"{outfile}.") diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000000..d2e8422e65 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +# requirements for building the docs + +sphinx +sphinx-multiversion +recommonmark + +# theme diff --git a/docs/source/_static/.empty.txt b/docs/source/_static/.empty.txt new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/source/_templates/versioning.html b/docs/source/_templates/versioning.html new file mode 100644 index 0000000000..7c5ab1474f --- /dev/null +++ b/docs/source/_templates/versioning.html @@ -0,0 +1,8 @@ +{% if versions %} +

{{ _('Versions') }}

+ +{% endif %} diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000000..3ec829d0d4 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,105 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import sys +from os.path import sep, abspath, dirname, join as pathjoin, exists +import recommonmark +from recommonmark.transform import AutoStructify +from sphinx.util.osutil import cd + +# we must set up Evennia and its paths for autodocs to work + +EV_ROOT = os.environ.get("EVDIR") +GAME_DIR = os.environ.get("EVGAMEDIR") + +if not (EV_ROOT and GAME_DIR): + print("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() + +print("Evennia root: {}, Game dir: {}".format(EV_ROOT, GAME_DIR)) + +sys.path.insert(1, EV_ROOT) +sys.path.insert(1, GAME_DIR) + +with cd(GAME_DIR): + # set up Evennia so its sources can be parsed + os.chdir(GAME_DIR) + + os.environ["DJANGO_SETTINGS_MODULE"] = "server.conf.settings" + + import django # noqa + django.setup() + + import evennia # noqa + evennia._init() + + +# -- 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' + +# -- 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.ext.napoleon", + "sphinx_multiversion" +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- 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' + +# 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 = {'**': + [ + "versioning.html" + ] +} + +# sphinx-multiversion config + +smv_branch_whitelist = r"^master$" +smv_outputdir_format = "versions" + sep + "{config.release}" + +# dynamic setup + +github_doc_root = "https://github.com/evennia/evennia-docs/" +def setup(app): + # recommonmark setup + app.add_config_value('recommonmark_config', { + 'url_resolver': lambda url: github_doc_root + url, + 'auto_toc_tree_section': 'Contents', + }, True) + app.add_transform(AutoStructify) diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 0000000000..85424ac477 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,10 @@ +Evennia documentation master file, created by + sphinx-quickstart on Sat Apr 4 09:58:05 2020. + +# Welcome to Evennia's documentation! + +## Indices and tables + +* [genindex](genindex) +* [modindex](modindex) +* [search](search) diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000000..afd5a1e7ad --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. Evennia documentation master file, created by + sphinx-quickstart on Sat Apr 4 23:52:36 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Evennia's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search`