Add dark/light switch to docs, include markdown manuals in doxygen generation

Author: SanderMertens

.github/workflows/pages.yml

@@ -34,11 +34,10 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v2
 
-      - name: Install Doxygen
-        run: sudo apt-get install doxygen -y
-        
-      - name: Generate docs
-        run: doxygen docs/Doxyfile
+      - name: Doxygen
+        uses: mattnotmitt/[email protected]
+        with:
+          doxyfile-path: 'docs/cfg/Doxyfile'
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v1

docs/Docs.md

@@ -1,18 +1,18 @@
-# Flecs Documentation
+# Documentation
 
 ## Getting Started
-- [FAQ](/flecs/#/docs/FAQ)
-- [Quickstart](/flecs/#/docs/Quickstart)
-- [Designing with Flecs](/flecs/#/docs/DesignWithFlecs)
+- [FAQ](/flecs/docs/api/html/md_docs_FAQ.html)
+- [Quickstart](/flecs/docs/api/html/md_docs_Quickstart.html)
+- [Designing with Flecs](/flecs/docs/api/html/md_docs_DesignWithFlecs.html)
 - [Getting Started with Unreal Engine](https://github.com/PreyK/Unreal-Minimum-Viable-Flecs)
 
 ## Manuals
-- [Manual](/flecs/#/docs/Manual)
-- [Query Manual](/flecs/#/docs/Queries)
-- [Systems Manual](/flecs/#/docs/Systems)
-- [Relationships Manual](/flecs/#/docs/Relationships)
-- [JSON Format Manual](/flecs/#/docs/JsonFormat)
-- [REST API Manual](/flecs/#/docs/RestApi)
+- [Manual](/flecs/docs/api/html/md_docs_Manual.html)
+- [Query Manual](/flecs/docs/api/html/md_docs_Queries.html)
+- [Systems Manual](/flecs/docs/api/html/md_docs_Systems.html)
+- [Relationships Manual](/flecs/docs/api/html/md_docs_Relationships.html)
+- [JSON Format Manual](/flecs/docs/api/html/md_docs_JsonFormat.html)
+- [REST API Manual](/flecs/docs/api/html/md_docs_RestApi.html)
 
 ## API reference
  - [C API](/flecs/docs/api/html/group__c.html)

docs/Manual.md

@@ -1,4 +1,4 @@
-# Flecs Manual
+# Manual
 
 ## Introduction
 Nobody likes to read manuals, and you should be able to get up and running with Flecs by using the quickstart, by looking at examples and by checking the documentation in the flecs header files. However, if you truly want to know how something works, or why it works that way, the manual is the right place to go. With that said, the manual is not exhaustive, and it complements the other sources of documentation.
@@ -27,19 +27,19 @@ There are few things as satisfying as building games. If nothing else, Flecs has
 
 ### High level architecture
 This diagram provides an overview of how entities, components, tables, queries, filters and systems are wired together.
-![Architecture diagram](flecs-architecture-overview.png)
+![Architecture diagram](img/flecs-architecture-overview.png)
 
 ### Component add flow
 This diagram provides an overview of the different steps that occur when adding a component to an entity. The diagram shows when component lifecycle callbacks, OnAdd triggers, OnSet systems, UnSet systems and monitors are invoked. Additionally the diagram shows how the defer mechanism is integrated with the listed Flecs operations.
-![Component add flow](flecs-add-component-flow.png)
+![Component add flow](img/flecs-add-component-flow.png)
 
 ### Component remove flow
 This diagram provides an overview of the different steps that occur when removing a component from an entity. The diagram shows when component lifecycle callbacks, OnRemove triggers, OnSet systems, UnSet systems and monitors are invoked. Additionally the diagram shows how the defer mechanism is integrated with the listed Flecs operations.
-![Component remove flow](flecs-remove-component-flow.png)
+![Component remove flow](img/flecs-remove-component-flow.png)
 
 ### Staging flow
 This diagram provides an overview of what happens when an application uses staging. Staging is a lockless mechanism that lets threads concurrently read & perform structural changes on the store. Changes are temporarily stored in a command queue per stage, which can be merged with the store when convenient.
-![Staging flow](flecs-staging-flow.png)
+![Staging flow](img/flecs-staging-flow.png)
 
 ## API design
 

docs/Quickstart.md

@@ -1,10 +1,10 @@
-# Flecs Quickstart
+# Quickstart
 This document provides a quick overview of the different features and concepts in Flecs with short examples. This is a good resource if you're just getting started or just want to get a better idea of what kind of features are available in Flecs!
 
 ## Overview
 This shows an overview of all the different concepts in Flecs and how they wire together. The sections in the quickstart go over them in more detail and with code examples.
 
-![Flecs Overview](flecs-quickstart-overview.png)
+![Flecs Overview](img/flecs-quickstart-overview.png)
 
 ## World
 The world is the container for all ECS data. It stores the entities and their components, does queries and runs systems. Typically there is only a single world, but there is no limit on the number of worlds an application can create.

docs/RestApi.md

@@ -66,7 +66,7 @@ An application with REST enabled can be remotely monitored with the [Flecs Explo
 
 When the connection is successful, the Explorer should look similar to this:
 
-![Remote Explorer](explorer-remote.png)
+![Remote Explorer](img/explorer-remote.png)
 
 The remote icon next to the title should be visible. If the connection is not successful it could be that the explorer did not receive a response fast enough. To force the explorer to connect remotely, add `?remote=true` to the request: https://flecs.dev/explorer?remote=true.
 

docs/Systems.md

@@ -1,4 +1,4 @@
-# Systems Manual
+# Systems
 Systems are queries + a function that can be ran manually or get scheduled as part of a pipeline. To use systems, applications must build Flecs with the `FLECS_SYSTEM` addon (enabled by default).
 
 An example of a simple system:

docs/Doxyfile renamed to docs/cfg/Doxyfile

@@ -42,26 +42,26 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = flecs
+PROJECT_NAME           = Flecs
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 3.1
+PROJECT_NUMBER         = v3.1
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          =
+PROJECT_BRIEF          = A fast entity component system (ECS) for C & C++
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           =
+PROJECT_LOGO           = 
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
@@ -901,7 +901,16 @@ WARN_LOGFILE           =
 INPUT                  = include/flecs.h \
                          include/flecs/os_api.h \
                          include/flecs/addons \
-                         docs/Docs.md
+                         docs/Docs.md \
+                         docs/Quickstart.md \
+                         docs/FAQ.md \
+                         docs/DesignWithFlecs.md \
+                         docs/Manual.md \
+                         docs/Queries.md \
+                         docs/Systems.md \
+                         docs/Relationships.md \
+                         docs/RestApi.md \
+                         docs/JsonFormat.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1013,7 +1022,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = docs
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1232,7 +1241,7 @@ HTML_FILE_EXTENSION    = .html
 # of the possible markers and block names see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_HEADER            =
+HTML_HEADER            = docs/cfg/header.html
 
 # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
 # generated HTML page. If the tag is left blank doxygen will generate a standard
@@ -1267,7 +1276,10 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_STYLESHEET  = docs/cfg/doxygen-awesome.css \
+                         docs/cfg/doxygen-awesome-sidebar-only.css \
+                         docs/cfg/doxygen-awesome-sidebar-only-darkmode-toggle.css \
+                         docs/cfg/custom.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1277,7 +1289,10 @@ HTML_EXTRA_STYLESHEET  =
 # files will be copied as-is; there are no commands or markers available.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_FILES       =
+HTML_EXTRA_FILES       = docs/cfg/doxygen-awesome-darkmode-toggle.js \
+                         docs/cfg/doxygen-awesome-fragment-copy-button.js \
+                         docs/cfg/doxygen-awesome-paragraph-link.js \
+                         docs/cfg/doxygen-awesome-interactive-toc.js
 
 # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output
 # should be rendered with a dark or light theme. Default setting AUTO_LIGHT
@@ -1294,7 +1309,7 @@ HTML_EXTRA_FILES       =
 # The default value is: AUTO_LIGHT.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE        = AUTO_LIGHT
+HTML_COLORSTYLE        = LIGHT
 
 # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
 # will adjust the colors in the style sheet and background images according to
@@ -2680,7 +2695,3 @@ GENERATE_LEGEND        = YES
 # The default value is: YES.
 
 DOT_CLEANUP            = YES
-
-# Custom styling
-HTML_EXTRA_STYLESHEET  = docs/css/doxygen-awesome.css \
-                         docs/css/doxygen-awesome-sidebar-only.css

docs/cfg/custom.css

@@ -0,0 +1,82 @@
+@import url("https://fonts.googleapis.com/css?family=Roboto+Mono|Source+Sans+Pro:300,400,600");
+
+.github-corner svg {
+  fill: var(--primary-color);
+  color: var(--page-background-color);
+  width: 72px;
+  height: 72px;
+}
+
+@media screen and (max-width: 767px) {
+  .github-corner svg {
+    width: 50px;
+    height: 50px;
+  }
+  #projectnumber {
+    margin-right: 22px;
+  }
+}
+
+.next_section_button {
+  display: block;
+  padding: var(--spacing-large) 0 var(--spacing-small) 0;
+  color: var(--page-background-color);
+  user-select: none;
+}
+
+.alter-theme-button:hover {
+  background: var(--primary-dark-color);
+}
+
+html.dark-mode .darkmode_inverted_image img, /* < doxygen 1.9.3 */
+html.dark-mode .darkmode_inverted_image object[type="image/svg+xml"] /* doxygen 1.9.3 */ {
+  filter: brightness(87%) hue-rotate(180deg) invert();
+}
+
+.bordered_image {
+  border-radius: var(--border-radius-small);
+  border: 1px solid var(--separator-color);
+  display: inline-block;
+  overflow: hidden;
+}
+
+html.dark-mode .bordered_image img, /* < doxygen 1.9.3 */
+html.dark-mode .bordered_image object[type="image/svg+xml"] /* doxygen 1.9.3 */ {
+  border-radius: var(--border-radius-small);
+}
+
+html {
+  --primary-color: #42b983;
+  --fragment-link: #42b983;
+  --fragment-keywordflow: #ff7b72;
+  --spacing-small: 8px;
+  --content-maxwidth: 800px;
+  --font-family: 'Source Sans Pro', 'Helvetica Neue', Arial, sans-serif;
+  --font-family-monospace: 'Roboto Mono', Monaco, courier, monospace;
+  --fragment-lineheight: 24px;
+}
+
+html.dark-mode {
+  --primary-color: #42b983;
+  --page-background-color: #1a1d23;
+  --side-nav-background: #242832;
+  --separator-color: rgba(255,255,255,0.07);
+  --tablehead-background: #242832;
+  --code-background: #242832;
+  --fragment-background: #242832;
+  --fragment-link: #42b983;
+  --fragment-keywordflow: #ff7b72;
+}
+
+div.fragment {
+  padding-top: 25px !important;
+  padding-bottom: 25px !important;
+  padding-left: 20px !important;
+  border-radius: 0px;
+  border: none;
+}
+
+code {
+  border-radius: 0px;
+  border: none;
+}