From bb7afd306add29188358f3dafcf0c13f669210d1 Mon Sep 17 00:00:00 2001 From: Paul Ouellette Date: Fri, 12 Apr 2019 08:29:29 -0400 Subject: [PATCH] Add Mkdocs API site (#8133) * Add MkDocs API site --- .gitignore | 11 +++-- .gitlab-ci.yml | 16 +++++++ doc/lua_api.txt | 3 +- doc/mkdocs/build.sh | 43 ++++++++++++++++++ doc/mkdocs/code_tag.patch | 31 +++++++++++++ doc/mkdocs/docs/css/code_styles.css | 68 +++++++++++++++++++++++++++++ doc/mkdocs/docs/css/extra.css | 15 +++++++ doc/mkdocs/docs/img/favicon.ico | 1 + doc/mkdocs/lua_highlight.patch | 9 ++++ 9 files changed, 192 insertions(+), 5 deletions(-) create mode 100755 doc/mkdocs/build.sh create mode 100644 doc/mkdocs/code_tag.patch create mode 100644 doc/mkdocs/docs/css/code_styles.css create mode 100644 doc/mkdocs/docs/css/extra.css create mode 120000 doc/mkdocs/docs/img/favicon.ico create mode 100644 doc/mkdocs/lua_highlight.patch diff --git a/.gitignore b/.gitignore index 6591b84b..ca03604d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -## Editors and Development environments +## Editors and development environments *~ *.swp *.bak* @@ -25,7 +25,7 @@ gtags.files # Codelite *.project -## Files related to minetest development cycle +## Files related to Minetest development cycle /*.patch *.diff # GNU Patch reject file @@ -54,7 +54,7 @@ gtags.files minetest.conf debug.txt -## Other files generated by minetest +## Other files generated by Minetest screenshot_*.png testbm.txt @@ -63,6 +63,11 @@ doc/Doxyfile doc/html/ doc/doxygen_* +## MkDocs files +public/ +doc/mkdocs/docs/*.md +doc/mkdocs/mkdocs.yml + ## Build files CMakeFiles Makefile diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index b957fdb3..dbc53209 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -322,3 +322,19 @@ package:docker: - docker push ${CONTAINER_IMAGE}/server:$CI_COMMIT_SHA - docker push ${CONTAINER_IMAGE}/server:$CI_COMMIT_REF_NAME - docker push ${CONTAINER_IMAGE}/server:latest + +pages: + stage: deploy + image: python:3.7 + before_script: + - pip install pip==18.1 + - pip install git+https://github.com/Python-Markdown/markdown.git + - pip install git+https://github.com/mkdocs/mkdocs.git + - pip install pygments + script: + - cd doc/mkdocs && ./build.sh + artifacts: + paths: + - public + only: + - master diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 41e8e0c9..870daba0 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -4,9 +4,8 @@ Minetest Lua Modding API Reference * More information at * Developer Wiki: - Introduction -============ +------------ Content and functionality can be added to Minetest using Lua scripting in run-time loaded mods. diff --git a/doc/mkdocs/build.sh b/doc/mkdocs/build.sh new file mode 100755 index 00000000..48ffbbad --- /dev/null +++ b/doc/mkdocs/build.sh @@ -0,0 +1,43 @@ +#!/bin/sh -e + +# Patch Pygments and Python-Markdown +PYGMENTS_FILE=$(pip show pygments | awk '/Location/ { print $2 }')/pygments/formatters/html.py +MARKDOWN_FILE=$(pip show markdown | awk '/Location/ { print $2 }')/markdown/extensions/codehilite.py +patch -N -r - $PYGMENTS_FILE code_tag.patch || true +patch -N -r - $MARKDOWN_FILE lua_highlight.patch || true + +# Split lua_api.txt on top level headings +cat ../lua_api.txt | csplit -sz -f docs/section - '/^=/-1' '{*}' + +cat > mkdocs.yml << EOF +site_name: Minetest API Documentation +theme: + name: readthedocs + highlightjs: False +extra_css: + - css/code_styles.css + - css/extra.css +markdown_extensions: + - toc: + permalink: True + - codehilite +plugins: + - search: + separator: '[\s\-\.\(]+' +nav: +- "Home": index.md +EOF + +mv docs/section00 docs/index.md + +for f in docs/section* +do + title=$(head -1 $f) + fname=$(echo $title | tr '[:upper:]' '[:lower:]') + fname=$(echo $fname | sed 's/ /-/g') + fname=$(echo $fname | sed "s/'//g").md + mv $f docs/$fname + echo "- \"$title\": $fname" >> mkdocs.yml +done + +mkdocs build --site-dir ../../public diff --git a/doc/mkdocs/code_tag.patch b/doc/mkdocs/code_tag.patch new file mode 100644 index 00000000..3148bc2a --- /dev/null +++ b/doc/mkdocs/code_tag.patch @@ -0,0 +1,31 @@ +@@ -691,7 +691,7 @@ + yield tup + yield 0, '\n' + +- def _wrap_pre(self, inner): ++ def _wrap_pre_code(self, inner): + style = [] + if self.prestyles: + style.append(self.prestyles) +@@ -704,10 +704,10 @@ + + # the empty span here is to keep leading empty lines from being + # ignored by HTML parsers +- yield 0, ('') ++ yield 0, ('') + for tup in inner: + yield tup +- yield 0, '' ++ yield 0, '' + + def _format_lines(self, tokensource): + """ +@@ -815,7 +815,7 @@ + individual lines, in custom generators. See docstring + for `format`. Can be overridden. + """ +- return self._wrap_div(self._wrap_pre(source)) ++ return self._wrap_div(self._wrap_pre_code(source)) + + def format_unencoded(self, tokensource, outfile): + """ diff --git a/doc/mkdocs/docs/css/code_styles.css b/doc/mkdocs/docs/css/code_styles.css new file mode 100644 index 00000000..c135acd9 --- /dev/null +++ b/doc/mkdocs/docs/css/code_styles.css @@ -0,0 +1,68 @@ +.codehilite .hll { background-color: #ffffcc } +.codehilite .c { color: #408080; font-style: italic } /* Comment */ +/* .codehilite .err { border: 1px solid #FF0000 } /* Error */ +.codehilite .k { color: #008000; font-weight: bold } /* Keyword */ +.codehilite .o { color: #666666 } /* Operator */ +.codehilite .ch { color: #408080; font-style: italic } /* Comment.Hashbang */ +.codehilite .cm { color: #408080; font-style: italic } /* Comment.Multiline */ +.codehilite .cp { color: #BC7A00 } /* Comment.Preproc */ +.codehilite .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */ +.codehilite .c1 { color: #408080; font-style: italic } /* Comment.Single */ +.codehilite .cs { color: #408080; font-style: italic } /* Comment.Special */ +.codehilite .gd { color: #A00000 } /* Generic.Deleted */ +.codehilite .ge { font-style: italic } /* Generic.Emph */ +.codehilite .gr { color: #FF0000 } /* Generic.Error */ +.codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.codehilite .gi { color: #00A000 } /* Generic.Inserted */ +.codehilite .go { color: #888888 } /* Generic.Output */ +.codehilite .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.codehilite .gs { font-weight: bold } /* Generic.Strong */ +.codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.codehilite .gt { color: #0044DD } /* Generic.Traceback */ +.codehilite .kc { color: #008000; font-weight: bold } /* Keyword.Constant */ +.codehilite .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ +.codehilite .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ +.codehilite .kp { color: #008000 } /* Keyword.Pseudo */ +.codehilite .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ +.codehilite .kt { color: #B00040 } /* Keyword.Type */ +.codehilite .m { color: #666666 } /* Literal.Number */ +.codehilite .s { color: #BA2121 } /* Literal.String */ +.codehilite .na { color: #7D9029 } /* Name.Attribute */ +.codehilite .nb { color: #008000 } /* Name.Builtin */ +.codehilite .nc { color: #0000FF; font-weight: bold } /* Name.Class */ +.codehilite .no { color: #880000 } /* Name.Constant */ +.codehilite .nd { color: #AA22FF } /* Name.Decorator */ +.codehilite .ni { color: #999999; font-weight: bold } /* Name.Entity */ +.codehilite .ne { color: #D2413A; font-weight: bold } /* Name.Exception */ +.codehilite .nf { color: #0000FF } /* Name.Function */ +.codehilite .nl { color: #A0A000 } /* Name.Label */ +.codehilite .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.codehilite .nt { color: #008000; font-weight: bold } /* Name.Tag */ +.codehilite .nv { color: #19177C } /* Name.Variable */ +.codehilite .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.codehilite .w { color: #bbbbbb } /* Text.Whitespace */ +.codehilite .mb { color: #666666 } /* Literal.Number.Bin */ +.codehilite .mf { color: #666666 } /* Literal.Number.Float */ +.codehilite .mh { color: #666666 } /* Literal.Number.Hex */ +.codehilite .mi { color: #666666 } /* Literal.Number.Integer */ +.codehilite .mo { color: #666666 } /* Literal.Number.Oct */ +.codehilite .sa { color: #BA2121 } /* Literal.String.Affix */ +.codehilite .sb { color: #BA2121 } /* Literal.String.Backtick */ +.codehilite .sc { color: #BA2121 } /* Literal.String.Char */ +.codehilite .dl { color: #BA2121 } /* Literal.String.Delimiter */ +.codehilite .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ +.codehilite .s2 { color: #BA2121 } /* Literal.String.Double */ +.codehilite .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ +.codehilite .sh { color: #BA2121 } /* Literal.String.Heredoc */ +.codehilite .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ +.codehilite .sx { color: #008000 } /* Literal.String.Other */ +.codehilite .sr { color: #BB6688 } /* Literal.String.Regex */ +.codehilite .s1 { color: #BA2121 } /* Literal.String.Single */ +.codehilite .ss { color: #19177C } /* Literal.String.Symbol */ +.codehilite .bp { color: #008000 } /* Name.Builtin.Pseudo */ +.codehilite .fm { color: #0000FF } /* Name.Function.Magic */ +.codehilite .vc { color: #19177C } /* Name.Variable.Class */ +.codehilite .vg { color: #19177C } /* Name.Variable.Global */ +.codehilite .vi { color: #19177C } /* Name.Variable.Instance */ +.codehilite .vm { color: #19177C } /* Name.Variable.Magic */ +.codehilite .il { color: #666666 } /* Literal.Number.Integer.Long */ diff --git a/doc/mkdocs/docs/css/extra.css b/doc/mkdocs/docs/css/extra.css new file mode 100644 index 00000000..8fde9f89 --- /dev/null +++ b/doc/mkdocs/docs/css/extra.css @@ -0,0 +1,15 @@ +/* Fix partly obscured last TOC element */ +.wy-menu { + padding-bottom: 20px; +} + +/* Use Minetest green instead of blue */ +.wy-nav-content a { + color: hsl(100, 40%, 40%); +} +.wy-nav-content a:hover { + color: hsl(100, 30%, 30%); +} +.wy-side-nav-search, .wy-nav-top, .wy-menu-vertical a:active { + background: hsl(100, 40%, 40%); +} diff --git a/doc/mkdocs/docs/img/favicon.ico b/doc/mkdocs/docs/img/favicon.ico new file mode 120000 index 00000000..cac34a30 --- /dev/null +++ b/doc/mkdocs/docs/img/favicon.ico @@ -0,0 +1 @@ +../../../../misc/minetest-icon.ico \ No newline at end of file diff --git a/doc/mkdocs/lua_highlight.patch b/doc/mkdocs/lua_highlight.patch new file mode 100644 index 00000000..bd97612e --- /dev/null +++ b/doc/mkdocs/lua_highlight.patch @@ -0,0 +1,9 @@ +@@ -77,7 +77,7 @@ + css_class="codehilite", lang=None, style='default', + noclasses=False, tab_length=4, hl_lines=None, use_pygments=True): + self.src = src +- self.lang = lang ++ self.lang = "lua" + self.linenums = linenums + self.guess_lang = guess_lang + self.css_class = css_class