diff --git a/.github/workflows/gh-pages-docs.yml b/.github/workflows/gh-pages-docs.yml new file mode 100644 index 0000000..9ad82e4 --- /dev/null +++ b/.github/workflows/gh-pages-docs.yml @@ -0,0 +1,28 @@ +name: gh-pages-docs + +on: + workflow_dispatch: + +jobs: + doxygen: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + submodules: true + fetch-depth: 0 + + - name: Install Doxygen + run: sudo apt-get install doxygen + + - name: Generate documentation + working-directory: docs + run: doxygen + + - name: Deploy + uses: JamesIves/github-pages-deploy-action@v4.5.0 + with: + branch: gh-pages + folder: docs/output/html + target-folder: docs diff --git a/.gitmodules b/.gitmodules index bb7f6de..40a719d 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,6 @@ [submodule "vendor/maplibre-native"] path = vendor/maplibre-native url = https://github.com/maplibre/maplibre-native.git +[submodule "docs/doxygen-awesome-css"] + path = docs/doxygen-awesome-css + url = https://github.com/jothepro/doxygen-awesome-css.git diff --git a/docs/Doxyfile b/docs/Doxyfile index 61e9b91..1dad40b 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -42,7 +42,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "QMapLibre" +PROJECT_NAME = "MapLibre Native for Qt" # 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 @@ -61,7 +61,7 @@ PROJECT_BRIEF = # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = +PROJECT_LOGO = logo.svg # With the PROJECT_ICON tag one can specify an icon that is included in the tabs # when the HTML document is shown. Doxygen will copy the logo to the output @@ -950,6 +950,7 @@ WARN_LOGFILE = # Note: If this tag is empty the current directory is searched. INPUT = ../src/core +INPUT += MAINPAGE.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 @@ -1165,7 +1166,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = MAINPAGE.md # The Fortran standard specifies that for fixed formatted Fortran code all # characters from position 72 are to be considered as comment. A common @@ -1325,7 +1326,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 = 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 @@ -1335,7 +1336,7 @@ HTML_HEADER = # that doxygen normally uses. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_FOOTER = +HTML_FOOTER = footer.html # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # sheet that is used by each HTML page. It can be used to fine-tune the look of @@ -1365,7 +1366,9 @@ HTML_STYLESHEET = # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \ + doxygen-awesome-css/doxygen-awesome-sidebar-only.css \ + doxygen-awesome-css/doxygen-awesome-sidebar-only-darkmode-toggle.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 @@ -1375,7 +1378,11 @@ 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 = favicon.ico \ + doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js \ + doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js \ + doxygen-awesome-css/doxygen-awesome-paragraph-link.js \ + doxygen-awesome-css/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. @@ -1388,7 +1395,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 @@ -1399,7 +1406,7 @@ HTML_COLORSTYLE = AUTO_LIGHT # Minimum value: 0, maximum value: 359, default value: 220. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_HUE = 216 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors # in the HTML output. For a value of 0 the output will use gray-scales only. A @@ -1407,7 +1414,7 @@ HTML_COLORSTYLE_HUE = 220 # Minimum value: 0, maximum value: 255, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_SAT = 158 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the # luminance component of the colors in the HTML output. Values below 100 @@ -1418,7 +1425,7 @@ HTML_COLORSTYLE_SAT = 100 # Minimum value: 40, maximum value: 240, default value: 80. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE_GAMMA = 80 +HTML_COLORSTYLE_GAMMA = 98 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that @@ -1716,7 +1723,7 @@ DISABLE_INDEX = NO # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_TREEVIEW = NO +GENERATE_TREEVIEW = YES # When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the # FULL_SIDEBAR option determines if the side bar is limited to only the treeview @@ -1745,7 +1752,7 @@ ENUM_VALUES_PER_LINE = 4 # Minimum value: 0, maximum value: 1500, default value: 250. # This tag requires that the tag GENERATE_HTML is set to YES. -TREEVIEW_WIDTH = 250 +TREEVIEW_WIDTH = 335 # If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to # external symbols imported via tag files in a separate window. @@ -1956,7 +1963,7 @@ EXTRA_SEARCH_MAPPINGS = # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. # The default value is: YES. -GENERATE_LATEX = YES +GENERATE_LATEX = NO # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/docs/MAINPAGE.md b/docs/MAINPAGE.md new file mode 100644 index 0000000..a2b40ee --- /dev/null +++ b/docs/MAINPAGE.md @@ -0,0 +1,8 @@ +# Documentation + +This is the documentation of the public MapLibre Native bindings for Qt. +You would normally use this API in a Qt-based application. +If you are interested in the internals of MapLibre Native you can also look at +[Core C++ API](https://maplibre.org/maplibre-native/cpp/api/). + +The source code can be found [on GitHub](https://github.com/maplibre/maplibre-native-qt). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..e8fe80a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,28 @@ +# Doxygen documentation + +This directory contains the files needed to generate the documentation +of MapLibre Native Qt Bindings using [Doxygen](https://www.doxygen.nl). + +[Doxygen Awesome](https://jothepro.github.io/doxygen-awesome-css/index.html) +is used as a theme and is included as a submodule. +To update, simply check out a new version of the submodule. + +The `[MAINPAGE.md](./MAINPAGE.md)` file contains the contents of the first page +you see when you open the documentation website, +While `[footer.html](./footer.html)` contains the contents of the footer. + +To generate the documentation, run + +```shell +doxygen +``` + +in this directory. + +While working on the documentation you might find it useful to run a file server. +For example, you can use: + +```shell +cd output/html +python -m http.server +``` diff --git a/docs/doxygen-awesome-css b/docs/doxygen-awesome-css new file mode 160000 index 0000000..df88fe4 --- /dev/null +++ b/docs/doxygen-awesome-css @@ -0,0 +1 @@ +Subproject commit df88fe4fdd97714fadfd3ef17de0b4401f804052 diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000..3dcce4a Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/footer.html b/docs/footer.html new file mode 100644 index 0000000..7f10bee --- /dev/null +++ b/docs/footer.html @@ -0,0 +1,17 @@ + + + + + + +
+$generatedby doxygen $doxygenversion +
+ + + diff --git a/docs/header.html b/docs/header.html new file mode 100644 index 0000000..fd44832 --- /dev/null +++ b/docs/header.html @@ -0,0 +1,92 @@ + + + + + + + + +$projectname: $title +$title + + + + + + + + + + + + + + +$treeview +$search +$mathjax +$darkmode + +$extrastylesheet + + + + + + + + + + + +
+ + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
$projectname $projectnumber +
+
$projectbrief
+ 		+
$projectbrief
+ 		$searchbox
$searchbox
+
+ + diff --git a/docs/logo.svg b/docs/logo.svg new file mode 100644 index 0000000..51198a7 --- /dev/null +++ b/docs/logo.svg @@ -0,0 +1,10 @@ + + + + + + + + + +