Skip to content

Commit 73b02ab

Browse files
committed
Add dark/light switch to docs, include markdown manuals in doxygen generation
1 parent 49972d5 commit 73b02ab

24 files changed

+647
-48
lines changed

.github/workflows/pages.yml

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,10 @@ jobs:
3434
- name: Setup Pages
3535
uses: actions/configure-pages@v2
3636

37-
- name: Install Doxygen
38-
run: sudo apt-get install doxygen -y
39-
40-
- name: Generate docs
41-
run: doxygen docs/Doxyfile
37+
- name: Doxygen
38+
uses: mattnotmitt/[email protected]
39+
with:
40+
doxyfile-path: 'docs/cfg/Doxyfile'
4241

4342
- name: Upload artifact
4443
uses: actions/upload-pages-artifact@v1

docs/Docs.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
1-
# Flecs Documentation
1+
# Documentation
22

33
## Getting Started
4-
- [FAQ](/flecs/#/docs/FAQ)
5-
- [Quickstart](/flecs/#/docs/Quickstart)
6-
- [Designing with Flecs](/flecs/#/docs/DesignWithFlecs)
4+
- [FAQ](/flecs/docs/api/html/md_docs_FAQ.html)
5+
- [Quickstart](/flecs/docs/api/html/md_docs_Quickstart.html)
6+
- [Designing with Flecs](/flecs/docs/api/html/md_docs_DesignWithFlecs.html)
77
- [Getting Started with Unreal Engine](https://github.com/PreyK/Unreal-Minimum-Viable-Flecs)
88

99
## Manuals
10-
- [Manual](/flecs/#/docs/Manual)
11-
- [Query Manual](/flecs/#/docs/Queries)
12-
- [Systems Manual](/flecs/#/docs/Systems)
13-
- [Relationships Manual](/flecs/#/docs/Relationships)
14-
- [JSON Format Manual](/flecs/#/docs/JsonFormat)
15-
- [REST API Manual](/flecs/#/docs/RestApi)
10+
- [Manual](/flecs/docs/api/html/md_docs_Manual.html)
11+
- [Query Manual](/flecs/docs/api/html/md_docs_Queries.html)
12+
- [Systems Manual](/flecs/docs/api/html/md_docs_Systems.html)
13+
- [Relationships Manual](/flecs/docs/api/html/md_docs_Relationships.html)
14+
- [JSON Format Manual](/flecs/docs/api/html/md_docs_JsonFormat.html)
15+
- [REST API Manual](/flecs/docs/api/html/md_docs_RestApi.html)
1616

1717
## API reference
1818
- [C API](/flecs/docs/api/html/group__c.html)

docs/Manual.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Flecs Manual
1+
# Manual
22

33
## Introduction
44
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
2727

2828
### High level architecture
2929
This diagram provides an overview of how entities, components, tables, queries, filters and systems are wired together.
30-
![Architecture diagram](flecs-architecture-overview.png)
30+
![Architecture diagram](img/flecs-architecture-overview.png)
3131

3232
### Component add flow
3333
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.
34-
![Component add flow](flecs-add-component-flow.png)
34+
![Component add flow](img/flecs-add-component-flow.png)
3535

3636
### Component remove flow
3737
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.
38-
![Component remove flow](flecs-remove-component-flow.png)
38+
![Component remove flow](img/flecs-remove-component-flow.png)
3939

4040
### Staging flow
4141
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.
42-
![Staging flow](flecs-staging-flow.png)
42+
![Staging flow](img/flecs-staging-flow.png)
4343

4444
## API design
4545

docs/Quickstart.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Flecs Quickstart
1+
# Quickstart
22
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!
33

44
## Overview
55
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.
66

7-
![Flecs Overview](flecs-quickstart-overview.png)
7+
![Flecs Overview](img/flecs-quickstart-overview.png)
88

99
## World
1010
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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ An application with REST enabled can be remotely monitored with the [Flecs Explo
6666

6767
When the connection is successful, the Explorer should look similar to this:
6868

69-
![Remote Explorer](explorer-remote.png)
69+
![Remote Explorer](img/explorer-remote.png)
7070

7171
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.
7272

docs/Systems.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Systems Manual
1+
# Systems
22
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).
33

44
An example of a simple system:

docs/Doxyfile renamed to docs/cfg/Doxyfile

Lines changed: 25 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -42,26 +42,26 @@ DOXYFILE_ENCODING = UTF-8
4242
# title of most generated pages and in a few other places.
4343
# The default value is: My Project.
4444

45-
PROJECT_NAME = flecs
45+
PROJECT_NAME = Flecs
4646

4747
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
4848
# could be handy for archiving the generated documentation or if some version
4949
# control system is used.
5050

51-
PROJECT_NUMBER = 3.1
51+
PROJECT_NUMBER = v3.1
5252

5353
# Using the PROJECT_BRIEF tag one can provide an optional one line description
5454
# for a project that appears at the top of each page and should give viewer a
5555
# quick idea about the purpose of the project. Keep the description short.
5656

57-
PROJECT_BRIEF =
57+
PROJECT_BRIEF = A fast entity component system (ECS) for C & C++
5858

5959
# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
6060
# in the documentation. The maximum height of the logo should not exceed 55
6161
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
6262
# the logo to the output directory.
6363

64-
PROJECT_LOGO =
64+
PROJECT_LOGO =
6565

6666
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
6767
# into which the generated documentation will be written. If a relative path is
@@ -901,7 +901,16 @@ WARN_LOGFILE =
901901
INPUT = include/flecs.h \
902902
include/flecs/os_api.h \
903903
include/flecs/addons \
904-
docs/Docs.md
904+
docs/Docs.md \
905+
docs/Quickstart.md \
906+
docs/FAQ.md \
907+
docs/DesignWithFlecs.md \
908+
docs/Manual.md \
909+
docs/Queries.md \
910+
docs/Systems.md \
911+
docs/Relationships.md \
912+
docs/RestApi.md \
913+
docs/JsonFormat.md
905914

906915
# This tag can be used to specify the character encoding of the source files
907916
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1013,7 +1022,7 @@ EXAMPLE_RECURSIVE = NO
10131022
# that contain images that are to be included in the documentation (see the
10141023
# \image command).
10151024

1016-
IMAGE_PATH =
1025+
IMAGE_PATH = docs
10171026

10181027
# The INPUT_FILTER tag can be used to specify a program that doxygen should
10191028
# invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1232,7 +1241,7 @@ HTML_FILE_EXTENSION = .html
12321241
# of the possible markers and block names see the documentation.
12331242
# This tag requires that the tag GENERATE_HTML is set to YES.
12341243

1235-
HTML_HEADER =
1244+
HTML_HEADER = docs/cfg/header.html
12361245

12371246
# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
12381247
# generated HTML page. If the tag is left blank doxygen will generate a standard
@@ -1267,7 +1276,10 @@ HTML_STYLESHEET =
12671276
# list). For an example see the documentation.
12681277
# This tag requires that the tag GENERATE_HTML is set to YES.
12691278

1270-
HTML_EXTRA_STYLESHEET =
1279+
HTML_EXTRA_STYLESHEET = docs/cfg/doxygen-awesome.css \
1280+
docs/cfg/doxygen-awesome-sidebar-only.css \
1281+
docs/cfg/doxygen-awesome-sidebar-only-darkmode-toggle.css \
1282+
docs/cfg/custom.css
12711283

12721284
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
12731285
# other source files which should be copied to the HTML output directory. Note
@@ -1277,7 +1289,10 @@ HTML_EXTRA_STYLESHEET =
12771289
# files will be copied as-is; there are no commands or markers available.
12781290
# This tag requires that the tag GENERATE_HTML is set to YES.
12791291

1280-
HTML_EXTRA_FILES =
1292+
HTML_EXTRA_FILES = docs/cfg/doxygen-awesome-darkmode-toggle.js \
1293+
docs/cfg/doxygen-awesome-fragment-copy-button.js \
1294+
docs/cfg/doxygen-awesome-paragraph-link.js \
1295+
docs/cfg/doxygen-awesome-interactive-toc.js
12811296

12821297
# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output
12831298
# should be rendered with a dark or light theme. Default setting AUTO_LIGHT
@@ -1294,7 +1309,7 @@ HTML_EXTRA_FILES =
12941309
# The default value is: AUTO_LIGHT.
12951310
# This tag requires that the tag GENERATE_HTML is set to YES.
12961311

1297-
HTML_COLORSTYLE = AUTO_LIGHT
1312+
HTML_COLORSTYLE = LIGHT
12981313

12991314
# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
13001315
# will adjust the colors in the style sheet and background images according to
@@ -2680,7 +2695,3 @@ GENERATE_LEGEND = YES
26802695
# The default value is: YES.
26812696

26822697
DOT_CLEANUP = YES
2683-
2684-
# Custom styling
2685-
HTML_EXTRA_STYLESHEET = docs/css/doxygen-awesome.css \
2686-
docs/css/doxygen-awesome-sidebar-only.css

docs/cfg/custom.css

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
@import url("https://fonts.googleapis.com/css?family=Roboto+Mono|Source+Sans+Pro:300,400,600");
2+
3+
.github-corner svg {
4+
fill: var(--primary-color);
5+
color: var(--page-background-color);
6+
width: 72px;
7+
height: 72px;
8+
}
9+
10+
@media screen and (max-width: 767px) {
11+
.github-corner svg {
12+
width: 50px;
13+
height: 50px;
14+
}
15+
#projectnumber {
16+
margin-right: 22px;
17+
}
18+
}
19+
20+
.next_section_button {
21+
display: block;
22+
padding: var(--spacing-large) 0 var(--spacing-small) 0;
23+
color: var(--page-background-color);
24+
user-select: none;
25+
}
26+
27+
.alter-theme-button:hover {
28+
background: var(--primary-dark-color);
29+
}
30+
31+
html.dark-mode .darkmode_inverted_image img, /* < doxygen 1.9.3 */
32+
html.dark-mode .darkmode_inverted_image object[type="image/svg+xml"] /* doxygen 1.9.3 */ {
33+
filter: brightness(87%) hue-rotate(180deg) invert();
34+
}
35+
36+
.bordered_image {
37+
border-radius: var(--border-radius-small);
38+
border: 1px solid var(--separator-color);
39+
display: inline-block;
40+
overflow: hidden;
41+
}
42+
43+
html.dark-mode .bordered_image img, /* < doxygen 1.9.3 */
44+
html.dark-mode .bordered_image object[type="image/svg+xml"] /* doxygen 1.9.3 */ {
45+
border-radius: var(--border-radius-small);
46+
}
47+
48+
html {
49+
--primary-color: #42b983;
50+
--fragment-link: #42b983;
51+
--fragment-keywordflow: #ff7b72;
52+
--spacing-small: 8px;
53+
--content-maxwidth: 800px;
54+
--font-family: 'Source Sans Pro', 'Helvetica Neue', Arial, sans-serif;
55+
--font-family-monospace: 'Roboto Mono', Monaco, courier, monospace;
56+
--fragment-lineheight: 24px;
57+
}
58+
59+
html.dark-mode {
60+
--primary-color: #42b983;
61+
--page-background-color: #1a1d23;
62+
--side-nav-background: #242832;
63+
--separator-color: rgba(255,255,255,0.07);
64+
--tablehead-background: #242832;
65+
--code-background: #242832;
66+
--fragment-background: #242832;
67+
--fragment-link: #42b983;
68+
--fragment-keywordflow: #ff7b72;
69+
}
70+
71+
div.fragment {
72+
padding-top: 25px !important;
73+
padding-bottom: 25px !important;
74+
padding-left: 20px !important;
75+
border-radius: 0px;
76+
border: none;
77+
}
78+
79+
code {
80+
border-radius: 0px;
81+
border: none;
82+
}

0 commit comments

Comments
 (0)