Added a sphinx-based doc setup. Its based on godot's. The colors still need work.

This commit is contained in:
Relintai 2019-12-26 16:15:27 +01:00
parent fb8df96bb3
commit 453280f6c3
11 changed files with 705 additions and 0 deletions

26
docs/.gitignore vendored Normal file
View File

@ -0,0 +1,26 @@
_build/
env/
classes/*
!classes/index.rst
__pycache__
*.pyc
*~
.directory
.vs/
.vscode/
*.mo
*.swo
*.swp
.DS_Store
[Tt]humbs.db
[Tt]humbs.db:encryptable
ehthumbs.db
ehthumbs_vista.db
__MACOSX
*.lnk
[Dd]esktop.ini

20
docs/Makefile Normal file
View File

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?= -j auto
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.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
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

273
docs/_static/css/custom.css vendored Normal file
View File

@ -0,0 +1,273 @@
/**
* Various tweaks to the Read the Docs theme to better conform with Godot's visual identity.
*/
:root {
--navbar-background-color: #292c37;
--navbar-background-color-hover: #292c37;
--navbar-background-color-active: #212d51;
--navbar-current-background-color: #000;
--navbar-current-background-color-hover: #1c1f26;
--navbar-current-background-color-active: #131e3b;
--navbar-level-1-color: #fff;
--navbar-level-2-color: #f0f8ff;
--navbar-level-3-color: #ddcd8d;
--navbar-heading-color: #d7bd6f;
--link-color-active: #105078;
--code-literal-color: #d04c60;
--highlight-background-color: #f5ffe1;
--input-background-color: #fcfcfc;
--input-focus-border-color: #5f8cff;
}
body,
h1,
h2,
h3,
h4,
h5,
h6,
input[type="text"],
input[type="button"],
input[type="reset"],
input[type="submit"],
textarea,
legend,
.btn,
.rst-content .toctree-wrapper p.caption,
.rst-versions {
/* Use a system font stack for better performance (no Web fonts required) */
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
}
h1,
h2,
h3,
h4,
h5,
h6,
legend,
.rst-content .toctree-wrapper p.caption {
/* Use a lighter font for headers (Medium instead of Bold) */
font-weight: 500;
}
p,
article ul,
article ol,
.wy-plain-list-disc,
.wy-plain-list-decimal,
.rst-content ol.arabic,
.rst-content .section ul,
.rst-content .toctree-wrapper ul,
.rst-content .section ol {
/* Increase the line height slightly to account for the different font */
line-height: 25px;
}
a:hover {
text-decoration: underline;
}
a:active {
/* Add visual feedback when clicking on a link */
color: var(--link-color-active);
}
a.btn:hover {
text-decoration: none;
}
/* Code display tweaks */
code,
.rst-content tt,
.rst-content code {
font-size: 14px;
}
.rst-content tt.literal,
.rst-content code.literal {
color: var(--code-literal-color);
}
.rst-content pre.literal-block,
.rst-content div[class^="highlight"] pre,
.rst-content .linenodiv pre {
/* Increase the font size and line height in code blocks */
font-size: 14px;
line-height: 1.5;
}
.highlight {
background-color: var(--highlight-background-color);
}
/* Navigation bar logo and search */
.wy-side-nav-search {
background-color: var(--navbar-background-color);
}
.wy-side-nav-search > a:hover,
.wy-side-nav-search .wy-dropdown > a:hover {
background-color: var(--navbar-background-color-hover);
}
.wy-side-nav-search > a:active,
.wy-side-nav-search .wy-dropdown > a:active {
background-color: var(--navbar-background-color-active);
}
.wy-side-nav-search input[type="text"] {
background-color: var(--input-background-color);
/* Avoid reflowing when toggling the focus state */
border: 2px solid transparent;
box-shadow: none;
/* Make visual feedback instant */
transition: none;
font-size: 14px;
}
.wy-side-nav-search input[type="text"]:focus {
border: 2px solid var(--input-focus-border-color);
}
/* Navigation bar */
.wy-nav-side {
background-color: var(--navbar-background-color);
}
.wy-menu-vertical header,
.wy-menu-vertical p.caption {
color: var(--navbar-heading-color);
/* Improves the appearance of uppercase text */
letter-spacing: 0.75px;
}
/* Mobile navigation */
.wy-nav-top,
.wy-nav-top a {
background-color: var(--navbar-background-color);
color: var(--navbar-level-1-color);
}
/* Version branch label below the logo */
.wy-side-nav-search > div.version {
color: var(--navbar-level-3-color);
opacity: 0.9;
}
/* First level of navigation items */
.wy-menu-vertical {
/* Account for the increased `toctree-expand` button margins */
width: 308px;
}
.wy-menu-vertical a {
color: var(--navbar-level-1-color);
}
.wy-menu-vertical a:hover {
background-color: var(--navbar-background-color-hover);
color: var(--navbar-level-1-color);
}
.wy-menu-vertical a:active {
background-color: var(--navbar-background-color-active);
}
.wy-menu-vertical li.toctree-l1.current > a {
border: none;
}
.wy-side-nav-search, .wy-menu-vertical a, .wy-menu-vertical a span.toctree-expand,
.wy-menu-vertical li.toctree-l2 a span.toctree-expand {
color: var(--navbar-level-3-color);
opacity: 0.9;
margin-right: 8px;
}
.wy-side-nav-search, .wy-menu-vertical a, .wy-menu-vertical a:hover span.toctree-expand,
.wy-menu-vertical li.toctree-l2 a:hover span.toctree-expand {
color: var(--navbar-level-2-color);
opacity: 1;
}
.wy-side-nav-search, .wy-menu-vertical a, .wy-menu-vertical a:active span.toctree-expand,
.wy-menu-vertical li.toctree-l2 a:active span.toctree-expand {
color: var(--navbar-level-1-color);
opacity: 1;
}
/* Second (and higher) levels of navigation items */
.wy-menu-vertical li.current a,
.wy-menu-vertical li.toctree-l2.current > a,
.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a,
.wy-menu-vertical li.toctree-l2.current li.toctree-l4 > a {
background-color: var(--navbar-current-background-color);
color: var(--navbar-level-2-color);
}
.wy-menu-vertical li.current a:hover,
.wy-menu-vertical li.toctree-l2.current > a:hover,
.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:hover,
.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a:hover {
background-color: var(--navbar-current-background-color-hover);
}
.wy-menu-vertical li.current a:active,
.wy-menu-vertical li.toctree-l2.current > a:active,
.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:active,
.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a:active {
background-color: var(--navbar-current-background-color-active);
}
/* Version selector (only visible on Read the Docs) */
.rst-versions {
background-color: var(--navbar-current-background-color);
}
.rst-versions a,
.rst-versions .rst-current-version,
.rst-versions .rst-current-version .fa,
.rst-versions .rst-other-versions dd a {
color: var(--navbar-level-1-color);
}
.rst-versions .rst-other-versions small {
color: var(--navbar-level-3-color);
}
.rst-versions .rst-other-versions dd a:hover {
text-decoration: underline;
}
.rst-versions .rst-other-versions {
color: var(--navbar-heading-color);
}
.rst-versions .rst-current-version {
background-color: var(--navbar-current-background-color);
}
.rst-versions .rst-current-version:hover {
background-color: var(--navbar-current-background-color-hover);
}
.rst-versions .rst-current-version:active {
background-color: var(--navbar-current-background-color-active);
}
/* Hide the obnoxious automatic highlight in search results */
.rst-content .highlighted {
background-color: transparent;
font-weight: inherit;
padding: 0;
}

7
docs/_templates/breadcrumbs.html vendored Normal file
View File

@ -0,0 +1,7 @@
{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
{% block breadcrumbs_aside %}
{% if not meta or meta.get('github_url') != 'hide' %}
{{ super() }}
{% endif %}
{% endblock %}

4
docs/_templates/layout.html vendored Normal file
View File

@ -0,0 +1,4 @@
{% extends "!layout.html" %}
{% block linktags %}
{{ super() }}
{% endblock %}

9
docs/classes/index.rst Normal file
View File

@ -0,0 +1,9 @@
Entity Spell System API
=======================
.. toctree::
:maxdepth: 1
:name: toc-class-ref
:glob:
class_*

117
docs/conf.py Normal file
View File

@ -0,0 +1,117 @@
# -*- coding: utf-8 -*-
# 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
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
# sys.path.insert(0, os.path.abspath('.'))
needs_sphinx = '1.3'
# -- Project information -----------------------------------------------------
project = 'Entity Spell System for GODOT'
copyright = '2019, Péter Magyar (Relintai)'
author = 'Péter Magyar (Relintai)'
version = 'latest'
release = 'latest'
# Parse Sphinx tags passed from RTD via environment
env_tags = os.getenv('SPHINX_TAGS')
if env_tags != None:
for tag in env_tags.split(','):
print("Adding Sphinx tag: %s" % tag.strip())
tags.add(tag.strip())
# -- 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.
sys.path.append(os.path.abspath('extensions'))
extensions = [
'gdscript', 'sphinx.ext.imgmath'
]
# 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 = ['_build', 'Thumbs.db', '.DS_Store']
source_suffix = '.rst'
source_encoding = 'utf-8-sig'
# GDScript syntax highlighting
from gdscript import GDScriptLexer
from sphinx.highlighting import lexers
lexers['gdscript'] = GDScriptLexer()
# Pygments (syntax highlighting) style to use
pygments_style = 'sphinx'
highlight_language = 'gdscript'
# -- Options for HTML output -------------------------------------------------
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
if on_rtd:
using_rtd_theme = True
# Theme options
html_theme_options = {
# 'typekit_id': 'hiw1hhg',
# 'analytics_id': '',
# 'sticky_navigation': True # Set to False to disable the sticky nav while scrolling.
'logo_only': True, # if we have a html_logo below, this shows /only/ the logo with no title text
'collapse_navigation': False, # Collapse navigation (False makes it tree-like)
# 'display_version': True, # Display the docs version
# 'navigation_depth': 4, # Depth of the headers shown in the navigation bar
}
# VCS options: https://docs.readthedocs.io/en/latest/vcs.html#github
html_context = {
"display_github": True, # Integrate GitHub
"github_user": "Relintai", # Username
"github_repo": "entity_spell_system", # Repo name
"github_version": "master", # Version
"conf_py_path": "/docs/", # Path in the checkout to the docs root
}
#html_logo = 'img/docs_logo.png'
# 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']
# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
'css/custom.css',
]
# Output file base name for HTML help builder
htmlhelp_basename = 'ESSdoc'
# -- Options for reStructuredText parser ----------------------------------
# Enable directives that insert the contents of external files
file_insertion_enabled = False

2
docs/create_class_docs.sh Executable file
View File

@ -0,0 +1,2 @@
python ../../../doc/tools/makerst.py ../doc_classes/ -o classes/

176
docs/extensions/gdscript.py Normal file
View File

@ -0,0 +1,176 @@
# -*- coding: utf-8 -*-
"""
pygments.lexers.gdscript
~~~~~~~~~~~~~~~~~~~~~~
Lexer for GDScript.
:copyright: Copyright 2xxx by The Godot Engine Community
:license: MIT.
modified by Daniel J. Ramirez <djrmuv@gmail.com> based on the original python.py pygment
"""
import re
from pygments.lexer import Lexer, RegexLexer, include, bygroups, using, \
default, words, combined, do_insertions
from pygments.util import get_bool_opt, shebang_matches
from pygments.token import Text, Comment, Operator, Keyword, Name, String, \
Number, Punctuation, Generic, Other, Error
from pygments import unistring as uni
__all__ = ['GDScriptLexer']
line_re = re.compile('.*?\n')
class GDScriptLexer(RegexLexer):
"""
For `Godot source code <https://www.godotengine.org>`_ source code.
"""
name = 'GDScript'
aliases = ['gdscript', 'gd']
filenames = ['*.gd']
mimetypes = ['text/x-gdscript', 'application/x-gdscript']
def innerstring_rules(ttype):
return [
# the old style '%s' % (...) string formatting
(r'%(\(\w+\))?[-#0 +]*([0-9]+|[*])?(\.([0-9]+|[*]))?'
'[hlL]?[E-GXc-giorsux%]', String.Interpol),
# backslashes, quotes and formatting signs must be parsed one at a time
(r'[^\\\'"%\n]+', ttype),
(r'[\'"\\]', ttype),
# unhandled string formatting sign
(r'%', ttype),
# newlines are an error (use "nl" state)
]
tokens = {
'root': [
(r'\n', Text),
(r'^(\s*)([rRuUbB]{,2})("""(?:.|\n)*?""")',
bygroups(Text, String.Affix, String.Doc)),
(r"^(\s*)([rRuUbB]{,2})('''(?:.|\n)*?''')",
bygroups(Text, String.Affix, String.Doc)),
(r'[^\S\n]+', Text),
(r'#.*$', Comment.Single),
(r'[]{}:(),;[]', Punctuation),
(r'\\\n', Text),
(r'\\', Text),
(r'(in|and|or|not)\b', Operator.Word),
(r'!=|==|<<|>>|&&|\+=|-=|\*=|/=|%=|&=|\|=|\|\||[-~+/*%=<>&^.!|$]', Operator),
include('keywords'),
(r'(func)((?:\s|\\\s)+)', bygroups(Keyword, Text), 'funcname'),
(r'(class)((?:\s|\\\s)+)', bygroups(Keyword, Text), 'classname'),
include('builtins'),
('([rR]|[uUbB][rR]|[rR][uUbB])(""")',
bygroups(String.Affix, String.Double), 'tdqs'),
("([rR]|[uUbB][rR]|[rR][uUbB])(''')",
bygroups(String.Affix, String.Single), 'tsqs'),
('([rR]|[uUbB][rR]|[rR][uUbB])(")',
bygroups(String.Affix, String.Double), 'dqs'),
("([rR]|[uUbB][rR]|[rR][uUbB])(')",
bygroups(String.Affix, String.Single), 'sqs'),
('([uUbB]?)(""")', bygroups(String.Affix, String.Double),
combined('stringescape', 'tdqs')),
("([uUbB]?)(''')", bygroups(String.Affix, String.Single),
combined('stringescape', 'tsqs')),
('([uUbB]?)(")', bygroups(String.Affix, String.Double),
combined('stringescape', 'dqs')),
("([uUbB]?)(')", bygroups(String.Affix, String.Single),
combined('stringescape', 'sqs')),
include('name'),
include('numbers'),
],
'keywords': [
(words((
'and', 'in', 'not', 'or', 'as', 'breakpoint', 'class', 'class_name',
'extends', 'is', 'func', 'setget', 'signal', 'tool', 'const',
'enum', 'export', 'onready', 'static', 'var', 'break', 'continue',
'if', 'elif', 'else', 'for', 'pass', 'return', 'match', 'while',
'remote', 'master', 'puppet', 'remotesync', 'mastersync',
'puppetsync'), suffix=r'\b'),
Keyword),
],
'builtins': [
(words((
'Color8', 'ColorN', 'abs', 'acos', 'asin', 'assert', 'atan', 'atan2',
'bytes2var', 'ceil', 'char', 'clamp', 'convert', 'cos', 'cosh',
'db2linear', 'decimals', 'dectime', 'deg2rad', 'dict2inst',
'ease', 'exp', 'floor', 'fmod', 'fposmod', 'funcref', 'hash',
'inst2dict', 'instance_from_id', 'is_inf', 'is_nan', 'lerp',
'linear2db', 'load', 'log', 'max', 'min', 'nearest_po2', 'pow',
'preload', 'print', 'print_stack', 'printerr', 'printraw',
'prints', 'printt', 'rad2deg', 'rand_range', 'rand_seed',
'randf', 'randi', 'randomize', 'range', 'round', 'seed', 'sign',
'sin', 'sinh', 'sqrt', 'stepify', 'str', 'str2var', 'tan',
'tan', 'tanh', 'type_exist', 'typeof', 'var2bytes', 'var2str',
'weakref', 'yield'),
prefix=r'(?<!\.)', suffix=r'\b'),
Name.Builtin),
(r'((?<!\.)(self|false|true)|(PI|TAU|NAN|INF)'
r')\b', Name.Builtin.Pseudo),
(words((
'bool', 'int', 'float', 'String', 'NodePath'
'Vector2', 'Rect2', 'Transform2D',
'Vector3', 'Rect3', 'Plane', 'Quat', 'Basis', 'Transform',
'Color', "RID", 'Object', 'NodePath', 'Dictionary',
'Array', 'PoolByteArray', 'PoolIntArray', 'PoolRealArray',
'PoolStringArray', 'PoolVector2Array', 'PoolVector3Array', 'PoolColorArray',
'null',
), prefix=r'(?<!\.)', suffix=r'\b'), Name.Builtin.Type),
],
'numbers': [
(r'(\d+\.\d*|\d*\.\d+)([eE][+-]?[0-9]+)?j?', Number.Float),
(r'\d+[eE][+-]?[0-9]+j?', Number.Float),
(r'0[xX][a-fA-F0-9]+', Number.Hex),
(r'\d+j?', Number.Integer)
],
'name': [
('[a-zA-Z_]\w*', Name),
],
'funcname': [
('[a-zA-Z_]\w*', Name.Function, '#pop'),
default('#pop'),
],
'classname': [
('[a-zA-Z_]\w*', Name.Class, '#pop')
],
'stringescape': [
(r'\\([\\abfnrtv"\']|\n|N\{.*?\}|u[a-fA-F0-9]{4}|'
r'U[a-fA-F0-9]{8}|x[a-fA-F0-9]{2}|[0-7]{1,3})', String.Escape)
],
'strings-single': innerstring_rules(String.Single),
'strings-double': innerstring_rules(String.Double),
'dqs': [
(r'"', String.Double, '#pop'),
(r'\\\\|\\"|\\\n', String.Escape), # included here for raw strings
include('strings-double')
],
'sqs': [
(r"'", String.Single, '#pop'),
(r"\\\\|\\'|\\\n", String.Escape), # included here for raw strings
include('strings-single')
],
'tdqs': [
(r'"""', String.Double, '#pop'),
include('strings-double'),
(r'\n', String.Double)
],
'tsqs': [
(r"'''", String.Single, '#pop'),
include('strings-single'),
(r'\n', String.Single)
],
}
def setup(sphinx):
sphinx.add_lexer('gdscript', GDScriptLexer())
return {
'parallel_read_safe': True,
'parallel_write_safe': True,
}

36
docs/index.rst Normal file
View File

@ -0,0 +1,36 @@
.. Entity-Spell System documentation master file, created by
sphinx-quickstart on Thu Dec 26 14:30:34 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Entity-Spell System's documentation!
===============================================
.. toctree::
:maxdepth: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. toctree::
:maxdepth: 1
:caption: Class reference
:name: sec-class-ref
classes/index
.. Indices and tables
.. ------------------
..
.. * :ref:`genindex`
.. * :ref:`modindex`
.. * :ref:`search`

35
docs/make.bat Normal file
View File

@ -0,0 +1,35 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
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