Skip to content

Commit e1f70a6

Browse files
authored
Merge pull request #7 from Simple-Robotics/topic/new-look-docs
[doc] Revamp/modernize visual look of documentation, update Doxygen config options
2 parents 6b741eb + bf8ce07 commit e1f70a6

File tree

11 files changed

+2918
-223
lines changed

11 files changed

+2918
-223
lines changed

CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
2121
- bindings/python : Add missing arg names in `visualizer-visitor.hpp`
2222
- use deprecation, warning macros already provided by jrl-cmakemodules
2323
- renamed `PINOCCHIO_PRAGMA_DEPRECATED_HEADER` to `PINOCCHIO_DEPRECATED_MOVED_HEADER`
24+
- docs : update documentation stylesheet, fix some Doxygen config options
2425

2526
### Removed
2627

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,7 @@ The currently active core developers of **Pinocchio** are:
253253
- [Justin Carpentier](https://jcarpent.github.io) (Inria): main developer and manager of the project
254254
- [Guilhem Saurel](https://www.laas.fr/fr/annuaire/gsaurel) (LAAS-CNRS): CI/CD, packaging
255255
- [Etienne Arlaud](https://github.com/EtienneAr) (Inria): core developer
256-
- [Wilson Jallet](https://github.com/ManifoldFR) (LAAS-CNRS/Inria): extension of Python bindings, C++ visualization API
256+
- [Wilson Jallet](https://github.com/ManifoldFR) (Inria): extension of Python bindings, C++ visualization API
257257
- [Fabian Schramm](https://github.com/fabinsch) (Inria): core developper
258258
- [Stéphane Caron](https://scaron.info) (Inria): core developper
259259
- [Joris Vaillant](https://github.com/jorisv) (Inria): core developer and project manager

doc/Doxyfile.extra.in

Lines changed: 16 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -315,10 +315,11 @@ FILE_PATTERNS = *.cc *.cpp *.h *.hpp *.hh *.dox *.md *.py
315315
# Note that relative paths are relative to the directory from which doxygen is
316316
# run.
317317

318-
#EXCLUDE = @PROJECT_SOURCE_DIR@/doc/d-practical-exercises/src
318+
EXCLUDE = @PROJECT_SOURCE_DIR@/doc/d-practical-exercises/src
319319

320320
# Put them back for inclusion as whole files
321-
HTML_EXTRA_FILES += @PROJECT_SOURCE_DIR@/doc/d-practical-exercises/src
321+
HTML_EXTRA_FILES += @PROJECT_SOURCE_DIR@/doc/d-practical-exercises/src \
322+
@PROJECT_SOURCE_DIR@/doc/doxygen-awesome-darkmode-toggle.js
322323

323324
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
324325
# directories that are symbolic links (a Unix file system feature) are excluded
@@ -355,8 +356,7 @@ EXCLUDE_PATTERNS += CMake* \
355356
# wildcard * is used, a substring. Examples: ANamespace, AClass,
356357
# AClass::ANamespace, ANamespace::*Test
357358

358-
EXCLUDE_SYMBOLS = internal::* \
359-
*Visitor
359+
EXCLUDE_SYMBOLS = internal::*,detail*::**Visitor,boost::*,Eigen::*,eigenpy::*,std::*
360360

361361
# The IMAGE_PATH tag can be used to specify one or more files or
362362
# directories that contain image that are included in the documentation (see
@@ -397,12 +397,6 @@ VERBATIM_HEADERS = YES
397397

398398
ALPHABETICAL_INDEX = YES
399399

400-
# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
401-
# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
402-
# in which this list will be split (can be a number in the range [1..20])
403-
404-
COLS_IN_ALPHA_INDEX = 4
405-
406400
#---------------------------------------------------------------------------
407401
# configuration options related to the HTML output
408402
#---------------------------------------------------------------------------
@@ -413,7 +407,8 @@ COLS_IN_ALPHA_INDEX = 4
413407
# Doxygen will copy the logo to the output directory.
414408

415409
PROJECT_LOGO = @PROJECT_SOURCE_DIR@/doc/pinocchio.png
416-
HTML_EXTRA_FILES += pinocchio.png
410+
HTML_EXTRA_FILES += @PROJECT_SOURCE_DIR@/doc/pinocchio.png \
411+
@PROJECT_SOURCE_DIR@/doc/pinocchio.ico
417412

418413
# The HTML_HEADER tag can be used to specify a personal HTML header for
419414
# each generated HTML page. If it is left blank doxygen will generate a
@@ -427,60 +422,21 @@ HTML_EXTRA_FILES += pinocchio.png
427422
# changing the value of configuration settings such as GENERATE_TREEVIEW!
428423

429424
HTML_HEADER = @PROJECT_SOURCE_DIR@/doc/header.html
430-
HTML_EXTRA_FILES += @PROJECT_SOURCE_DIR@/doc/pinocchio.ico
431425

432426
# The HTML_FOOTER tag can be used to specify a personal HTML footer for
433427
# each generated HTML page. If it is left blank doxygen will generate a
434428
# standard footer.
435429

436-
HTML_FOOTER =
437-
438-
# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
439-
# style sheet that is used by each HTML page. It can be used to
440-
# fine-tune the look of the HTML output. If the tag is left blank doxygen
441-
# will generate a default style sheet. Note that doxygen will try to copy
442-
# the style sheet file to the HTML output directory, so don't put your own
443-
# style sheet in the HTML output directory as well, or it will be erased!
444-
# NOTE: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag,
445-
# as it is more robust and this tag (HTML_STYLESHEET)
446-
# will in the future become obsolete.
447-
448-
#HTML_STYLESHEET = @PROJECT_SOURCE_DIR@/doc/package.css
449-
450-
# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined
451-
# cascading style sheets that are included after the standard style sheets
452-
# created by doxygen. Using this option one can overrule certain style aspects.
453-
# This is preferred over using HTML_STYLESHEET since it does not replace
454-
# the standard style sheet and is therefore more robust against future updates.
455-
# Doxygen will copy the style sheet files to the output directory.
456-
457-
HTML_EXTRA_STYLESHEET = @PROJECT_SOURCE_DIR@/doc/customdoxygen.css
458-
459-
# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output.
460-
# Doxygen will adjust the colors in the style sheet and background images
461-
# according to this color. Hue is specified as an angle on a colorwheel,
462-
# see http://en.wikipedia.org/wiki/Hue for more information.
463-
# For instance the value 0 represents red, 60 is yellow, 120 is green,
464-
# 180 is cyan, 240 is blue, 300 purple, and 360 is red again.
465-
# The allowed range is 0 to 359.
466-
# The default is 220.
467-
468-
HTML_COLORSTYLE_HUE = 220
469-
470-
# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of
471-
# the colors in the HTML output. For a value of 0 the output will use
472-
# grayscales only. A value of 255 will produce the most vivid colors.
430+
HTML_FOOTER =
473431

474-
HTML_COLORSTYLE_SAT = 100
432+
FULL_SIDEBAR = NO
475433

476-
# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to
477-
# the luminance component of the colors in the HTML output. Values below
478-
# 100 gradually make the output lighter, whereas values above 100 make
479-
# the output darker. The value divided by 100 is the actual gamma applied,
480-
# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2,
481-
# and 100 does not change the gamma.
434+
HTML_EXTRA_STYLESHEET = @PROJECT_SOURCE_DIR@/doc/doxygen-awesome.css
482435

483-
HTML_COLORSTYLE_GAMMA = 80
436+
HTML_COLORSTYLE_HUE = 209
437+
HTML_COLORSTYLE_SAT = 255
438+
HTML_COLORSTYLE_GAMMA = 113
439+
HTML_COLORSTYLE = LIGHT
484440

485441
# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
486442
# documentation will contain sections that can be hidden and shown after the
@@ -534,7 +490,7 @@ ECLIPSE_DOC_ID = org.doxygen.@PACKAGE_NAME@
534490
# top of each HTML page. The value NO (the default) enables the index and
535491
# the value YES disables it.
536492

537-
DISABLE_INDEX = YES
493+
DISABLE_INDEX = NO
538494

539495
# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
540496
# structure should be generated to display hierarchical information.
@@ -608,7 +564,8 @@ PREDEFINED += EIGEN_MAKE_ALIGNED_OPERATOR_NEW \
608564
PINOCCHIO_WITH_URDFDOM \
609565
PINOCCHIO_WITH_CPPAD_SUPPORT \
610566
PINOCCHIO_WITH_CPPADCG_SUPPORT \
611-
PINOCCHIO_WITH_LUA5
567+
PINOCCHIO_DONT_INLINE \
568+
PINOCCHIO_NOEXCEPT=noexcept
612569

613570
# The following macros would be better treated with EXPAND_AS_DEFINED.
614571
# However, it was not working properly

doc/customdoxygen.css

Lines changed: 0 additions & 19 deletions
This file was deleted.
Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
/**
2+
3+
Doxygen Awesome
4+
https://github.com/jothepro/doxygen-awesome-css
5+
6+
MIT License
7+
8+
Copyright (c) 2021 - 2023 jothepro
9+
10+
Permission is hereby granted, free of charge, to any person obtaining a copy
11+
of this software and associated documentation files (the "Software"), to deal
12+
in the Software without restriction, including without limitation the rights
13+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14+
copies of the Software, and to permit persons to whom the Software is
15+
furnished to do so, subject to the following conditions:
16+
17+
The above copyright notice and this permission notice shall be included in all
18+
copies or substantial portions of the Software.
19+
20+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26+
SOFTWARE.
27+
28+
*/
29+
30+
class DoxygenAwesomeDarkModeToggle extends HTMLElement {
31+
// SVG icons from https://fonts.google.com/icons
32+
// Licensed under the Apache 2.0 license:
33+
// https://www.apache.org/licenses/LICENSE-2.0.html
34+
static lightModeIcon = `<svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#FCBF00"><rect fill="none" height="24" width="24"/><circle cx="12" cy="12" opacity=".3" r="3"/><path d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"/></svg>`
35+
static darkModeIcon = `<svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24px" viewBox="0 0 24 24" width="24px" fill="#FE9700"><rect fill="none" height="24" width="24"/><path d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27 C17.45,17.19,14.93,19,12,19c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z" opacity=".3"/><path d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"/></svg>`
36+
static title = "Toggle Light/Dark Mode"
37+
38+
static prefersLightModeInDarkModeKey = "prefers-light-mode-in-dark-mode"
39+
static prefersDarkModeInLightModeKey = "prefers-dark-mode-in-light-mode"
40+
41+
static _staticConstructor = function() {
42+
DoxygenAwesomeDarkModeToggle.enableDarkMode(DoxygenAwesomeDarkModeToggle.userPreference)
43+
// Update the color scheme when the browsers preference changes
44+
// without user interaction on the website.
45+
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => {
46+
DoxygenAwesomeDarkModeToggle.onSystemPreferenceChanged()
47+
})
48+
// Update the color scheme when the tab is made visible again.
49+
// It is possible that the appearance was changed in another tab
50+
// while this tab was in the background.
51+
document.addEventListener("visibilitychange", visibilityState => {
52+
if (document.visibilityState === 'visible') {
53+
DoxygenAwesomeDarkModeToggle.onSystemPreferenceChanged()
54+
}
55+
});
56+
}()
57+
58+
static init() {
59+
$(function() {
60+
$(document).ready(function() {
61+
const toggleButton = document.createElement('doxygen-awesome-dark-mode-toggle')
62+
toggleButton.title = DoxygenAwesomeDarkModeToggle.title
63+
toggleButton.updateIcon()
64+
65+
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', event => {
66+
toggleButton.updateIcon()
67+
})
68+
document.addEventListener("visibilitychange", visibilityState => {
69+
if (document.visibilityState === 'visible') {
70+
toggleButton.updateIcon()
71+
}
72+
});
73+
74+
$(document).ready(function(){
75+
document.getElementById("MSearchBox").parentNode.appendChild(toggleButton)
76+
})
77+
$(window).resize(function(){
78+
document.getElementById("MSearchBox").parentNode.appendChild(toggleButton)
79+
})
80+
})
81+
})
82+
}
83+
84+
constructor() {
85+
super();
86+
this.onclick=this.toggleDarkMode
87+
}
88+
89+
/**
90+
* @returns `true` for dark-mode, `false` for light-mode system preference
91+
*/
92+
static get systemPreference() {
93+
return window.matchMedia('(prefers-color-scheme: dark)').matches
94+
}
95+
96+
/**
97+
* @returns `true` for dark-mode, `false` for light-mode user preference
98+
*/
99+
static get userPreference() {
100+
return (!DoxygenAwesomeDarkModeToggle.systemPreference && localStorage.getItem(DoxygenAwesomeDarkModeToggle.prefersDarkModeInLightModeKey)) ||
101+
(DoxygenAwesomeDarkModeToggle.systemPreference && !localStorage.getItem(DoxygenAwesomeDarkModeToggle.prefersLightModeInDarkModeKey))
102+
}
103+
104+
static set userPreference(userPreference) {
105+
DoxygenAwesomeDarkModeToggle.darkModeEnabled = userPreference
106+
if(!userPreference) {
107+
if(DoxygenAwesomeDarkModeToggle.systemPreference) {
108+
localStorage.setItem(DoxygenAwesomeDarkModeToggle.prefersLightModeInDarkModeKey, true)
109+
} else {
110+
localStorage.removeItem(DoxygenAwesomeDarkModeToggle.prefersDarkModeInLightModeKey)
111+
}
112+
} else {
113+
if(!DoxygenAwesomeDarkModeToggle.systemPreference) {
114+
localStorage.setItem(DoxygenAwesomeDarkModeToggle.prefersDarkModeInLightModeKey, true)
115+
} else {
116+
localStorage.removeItem(DoxygenAwesomeDarkModeToggle.prefersLightModeInDarkModeKey)
117+
}
118+
}
119+
DoxygenAwesomeDarkModeToggle.onUserPreferenceChanged()
120+
}
121+
122+
static enableDarkMode(enable) {
123+
if(enable) {
124+
DoxygenAwesomeDarkModeToggle.darkModeEnabled = true
125+
document.documentElement.classList.add("dark-mode")
126+
document.documentElement.classList.remove("light-mode")
127+
} else {
128+
DoxygenAwesomeDarkModeToggle.darkModeEnabled = false
129+
document.documentElement.classList.remove("dark-mode")
130+
document.documentElement.classList.add("light-mode")
131+
}
132+
}
133+
134+
static onSystemPreferenceChanged() {
135+
DoxygenAwesomeDarkModeToggle.darkModeEnabled = DoxygenAwesomeDarkModeToggle.userPreference
136+
DoxygenAwesomeDarkModeToggle.enableDarkMode(DoxygenAwesomeDarkModeToggle.darkModeEnabled)
137+
}
138+
139+
static onUserPreferenceChanged() {
140+
DoxygenAwesomeDarkModeToggle.enableDarkMode(DoxygenAwesomeDarkModeToggle.darkModeEnabled)
141+
}
142+
143+
toggleDarkMode() {
144+
DoxygenAwesomeDarkModeToggle.userPreference = !DoxygenAwesomeDarkModeToggle.userPreference
145+
this.updateIcon()
146+
}
147+
148+
updateIcon() {
149+
if(DoxygenAwesomeDarkModeToggle.darkModeEnabled) {
150+
this.innerHTML = DoxygenAwesomeDarkModeToggle.darkModeIcon
151+
} else {
152+
this.innerHTML = DoxygenAwesomeDarkModeToggle.lightModeIcon
153+
}
154+
}
155+
}
156+
157+
customElements.define("doxygen-awesome-dark-mode-toggle", DoxygenAwesomeDarkModeToggle);

0 commit comments

Comments
 (0)