diff --git a/.gitignore b/.gitignore index 078133db5..617b6be5d 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,7 @@ android/ ios/ desktop/ build/ +_build/ coverage diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..8067b6f3e --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,14 @@ +# [Read the Docs] configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +sphinx: + builder: html + configuration: doc/_sphinx/conf.py + fail_on_warning: false + +python: + version: "3.8" + install: + - requirements: doc/_sphinx/requirements.txt diff --git a/doc/README.md b/doc/README.md index 6fb97f070..a8feca4ae 100644 --- a/doc/README.md +++ b/doc/README.md @@ -13,7 +13,7 @@ short). We also provide stand-alone packages that extend the Flame functionality: - [flame_audio](https://pub.dev/packages/flame_audio) Which provides audio capabilities using the - `audioplayers` package. + `audioplayers` package. - [flame_forge2d](https://pub.dev/packages/flame_forge2d) Which provides physics capabilities using our own `Box2D` port called `Forge2D`. - [flame_tiled](https://pub.dev/packages/flame_tiled) Which provides integration with the diff --git a/doc/_sphinx/Makefile b/doc/_sphinx/Makefile new file mode 100644 index 000000000..4762aa559 --- /dev/null +++ b/doc/_sphinx/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= -c . +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) diff --git a/doc/_sphinx/conf.py b/doc/_sphinx/conf.py new file mode 100644 index 000000000..fcf98ab61 --- /dev/null +++ b/doc/_sphinx/conf.py @@ -0,0 +1,75 @@ +# 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 + + +# -- Project information ----------------------------------------------------- + +project = 'Flame' +copyright = '2021, Blue Fire Team' +author = 'Blue Fire Team' + +root_doc = "index" + + +# -- 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 = [ + 'myst_parser', # Markdown support +] + +# Configuration options for MyST: +# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html +myst_enable_extensions = [ + 'dollarmath', + 'html_admonition', + 'html_image', + 'linkify', + 'replacements', + 'smartquotes', +] + +# Auto-generate link anchors for headers at levels H1 and H2 +myst_heading_anchors = 2 + +# 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', 'summary.md'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. +html_theme = "sphinx_book_theme" + +# See https://sphinx-book-theme.readthedocs.io/en/latest/customize/index.html +html_theme_options = { + "logo_only": True, + "path_to_docs": "doc", + "repository_branch": "main", + "repository_url": "https://github.com/flame-engine/flame", + "use_edit_page_button": True, + "use_repository_button": True, +} +html_title = "Flame" +html_logo = "images/logo_flame.png" +html_favicon = "images/favicon.ico" + +# Style for syntax highlighting +pygments_style = 'monokai' + +# 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 = ['images', 'styles'] + + +def setup(app): + """Add functions to the Sphinx setup.""" + app.add_css_file("custom.css") diff --git a/doc/_sphinx/images/favicon.ico b/doc/_sphinx/images/favicon.ico new file mode 100644 index 000000000..796fd293d Binary files /dev/null and b/doc/_sphinx/images/favicon.ico differ diff --git a/doc/_sphinx/images/logo_flame.png b/doc/_sphinx/images/logo_flame.png new file mode 100644 index 000000000..58b92c862 Binary files /dev/null and b/doc/_sphinx/images/logo_flame.png differ diff --git a/doc/_sphinx/make.bat b/doc/_sphinx/make.bat new file mode 100644 index 000000000..fc480977e --- /dev/null +++ b/doc/_sphinx/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=.. +set BUILDDIR=..\_build +set SPHINXOPTS=-c . + +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.https://www.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/doc/_sphinx/requirements.txt b/doc/_sphinx/requirements.txt new file mode 100644 index 000000000..35d22942a --- /dev/null +++ b/doc/_sphinx/requirements.txt @@ -0,0 +1,5 @@ +linkify-it-py>=1.0 +myst-parser>=0.15.2 +pygments>=2.10 +sphinx>=4.2 +sphinx-book-theme>=0.1.4 \ No newline at end of file diff --git a/doc/_sphinx/styles/custom.css b/doc/_sphinx/styles/custom.css new file mode 100644 index 000000000..e0ed85e9f --- /dev/null +++ b/doc/_sphinx/styles/custom.css @@ -0,0 +1,148 @@ +:root { + --pst-color-inline-code: 255, 140, 50; + --pst-color-link: 100, 150, 200; + --pst-color-preformatted-background: 50, 50, 50; + --pst-color-primary: 240, 240, 240; + --pst-color-sidebar-caption: 250, 250, 255; + --pst-color-sidebar-link: 150, 160, 170; + --pst-color-sidebar-link-active: 80, 190, 255; + --pst-color-text-base: 211, 211, 211; + --pst-color-toc-link: 130, 130, 130; +} + +body { + background-color: #3a3a3a; +} + +#site-navigation { + background-color: #202225; +} +#site-navigation::-webkit-scrollbar { + width: 4px; +} +#site-navigation::-webkit-scrollbar-track { + background: #202225; +} +#site-navigation::-webkit-scrollbar-thumb, +#site-navigation::-webkit-scrollbar-thumb:vertical { + background: #000; +} + + +.topbar .topbar-main button.topbarbtn { + background-color: #636363; + color: #2f2f2f; +} + +#navbar-toggler { + color: #777; +} + +.navbar_extra_footer { + display: none; +} + +div.navbar-brand-box { + padding: .5em 0 1em 0; +} + +div.navbar-brand-box a.navbar-brand { + display: flex; + align-items: center; +} + +div.navbar-brand-box a.navbar-brand img { + max-width: 24vh; + margin: 0; +} + +pre { + border: none; + box-shadow: 0px 0px 3px black; + color: #888; + position: relative; +} + +code { + background-color: #222; + border-radius: 3pt; + padding: 2pt 3pt; +} + +div[class^="highlight-"] pre:before { + background: black; + border-bottom-left-radius: 5px; + border-top-right-radius: 5px; + color: #58d0ff; + font-size: 80%; + padding: 1px 8px; + position: absolute; + right: 0; + top: 0; +} + +div.highlight-dart pre:before { + content: "dart"; +} +div.highlight-yaml pre:before { + content: "yaml"; + color: #5f5; +} +div.highlight-text pre:before { + content: "text"; + color: #666; +} + +/* Cancel some of the existing styles */ +#site-navigation nav ul.nav li a, #site-navigation nav ul.nav ul li a { + color: rgba(var(--pst-color-sidebar-link), 1); +} +#site-navigation nav ul.nav a:hover, #site-navigation nav ul.nav li.active>a, #site-navigation nav ul.nav li.active>a:hover { + color: rgba(var(--pst-color-sidebar-link-active), 1); +} +.bd-toc div.onthispage, .bd-toc .toc-entry a { + color: rgba(var(--pst-color-toc-link), 1); +} +.bd-toc nav { + background: inherit; +} +.bd-toc nav > .nav { + border-color: #111; +} +nav.bd-links p.caption { + margin-bottom: 0.2em; +} +main.bd-content #main-content h1 { + color: rgba(var(--pst-color-h1), 1); +} +main.bd-content #main-content h2 { + color: rgba(var(--pst-color-h2), 1); +} +main.bd-content #main-content h3 { + color: rgba(var(--pst-color-h3), 1); +} +main.bd-content #main-content h4 { + color: rgba(var(--pst-color-h4), 1); +} +main.bd-content #main-content h5 { + color: rgba(var(--pst-color-h5), 1); +} +#site-navigation h1.site-logo { + color: rgba(var(--pst-color-h1), 1); +} +.form-control { + background-color: transparent; +} +.topbar { + background-color: #3a3a3a; +} +.tocsection { + border-color: black; +} +main.bd-content #main-content .prev-next-bottom .right-next .prevnext-label, main.bd-content #main-content .prev-next-bottom .left-prev .prevnext-label { + color: #808080; +} + +.bd-sidebar .nav li>a { + padding: .1rem 1.5rem; +} diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 000000000..2ebc9b853 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,5 @@ +```{include} README.md +``` +```{eval-rst} +.. include:: toc.rst +``` \ No newline at end of file diff --git a/doc/splash_screen.md b/doc/splash_screen.md index 30eb41e30..63a98510e 100644 --- a/doc/splash_screen.md +++ b/doc/splash_screen.md @@ -1,4 +1,4 @@ -## Splash screen +# Splash screen ![](https://raw.githubusercontent.com/flame-engine/flame_splash_screen/main/demogif.gif) diff --git a/doc/structure.md b/doc/structure.md index b315c772a..857387c08 100644 --- a/doc/structure.md +++ b/doc/structure.md @@ -13,7 +13,7 @@ If using the following example code: The file structure Flame would expect to find the files in would be: -``` +```text . └── assets ├── audio @@ -27,7 +27,7 @@ Optionally you can split your `audio` folder into two subfolders, one for `music Don't forget to add these files to your `pubspec.yaml` file: -``` +```yaml flutter: assets: - assets/audio/explosion.mp3 diff --git a/doc/toc.rst b/doc/toc.rst new file mode 100644 index 000000000..ff38b8bb1 --- /dev/null +++ b/doc/toc.rst @@ -0,0 +1,49 @@ + +.. toctree:: + :caption: Basic concepts + :hidden: + + File structure + Game loop + Components + Platforms + Collision detection + Effects + Camera & Viewport + +.. toctree:: + :caption: Inputs + :hidden: + + Gesture input + Keyboard input + Other inputs + +.. toctree:: + :caption: Audio + :hidden: + + General audio + Background music + +.. toctree:: + :caption: Rendering + :hidden: + + Images, sprites and animations + Text rendering + Colors and palette + Particles + Layers + +.. toctree:: + :caption: Other Modules + :hidden: + + Util + Widgets + Forge2D + Oxygen + Tiled + Debugging + Splash screen