Skip to content

Commit

Permalink
minor doc updates (#236)
Browse files Browse the repository at this point in the history
- upgrades to doxygen v1.10.0
- adds custom CSS
- set doxygen's favicon
- fixes cross-link references
  • Loading branch information
2bndy5 authored Apr 6, 2024
1 parent 087af89 commit 7c30deb
Show file tree
Hide file tree
Showing 6 changed files with 121 additions and 13 deletions.
1 change: 1 addition & 0 deletions .github/workflows/doxygen.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,4 +36,5 @@ jobs:
uses: nRF24/.github/.github/workflows/build_docs.yaml@main
with:
deploy-gh-pages: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master') }}
doxygen-version: '1.10.0'
secrets: inherit
15 changes: 9 additions & 6 deletions docs/Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@
# Project related configuration options
#---------------------------------------------------------------------------

PROJECT_ICON = sphinx/_static/new_favicon.ico

# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
# double-quotes, unless you are using Doxywizard) that should identify the
# project for which the documentation is generated. This name is used in the
Expand Down Expand Up @@ -343,14 +345,15 @@ HTML_EXTRA_STYLESHEET = doxygen-custom.css

HTML_COLORSTYLE = TOGGLE

# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
# page will contain the date and time when the page was generated. Setting this
# to YES can help to show when doxygen was last run and thus if the
# documentation is up to date.
# If the TIMESTAMP tag is set different from NO then each generated page will contain
# the date or date and time when the page was generated. Setting this to NO can help
# when comparing the output of multiple runs.
#
# Possible values are: YES, NO, DATETIME and DATE.
#
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.

HTML_TIMESTAMP = YES
TIMESTAMP = DATE

# 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
Expand Down
104 changes: 104 additions & 0 deletions docs/doxygen-custom.css
Original file line number Diff line number Diff line change
@@ -1,3 +1,107 @@
table.markdownTable th {
color: unset;
}

/* overrides from default CSSS for some admonitions */
dl.note, dl.remark,
dl.warning, dl.attention {
color: unset;
}
dl.remark {
background: var(--remark-color-bg);
border-left: 8px solid var(--remark-color-hl);
}
dl.remark dt {
color: var(--remark-color-hl);
}

/* special rules to accent `/see` or `/sa` command output */
dl.see {
background: var(--seealso-color-bg);
border-left: 8px solid var(--seealso-color-hl);
}
dl.see dt {
color: var(--seealso-color-hl);
}
dl.see {
padding: 10px;
margin: 10px 0px;
overflow: hidden;
margin-left: 0;
border-radius: 4px;
}

/* admonition icons */
dl.note dt::before {
background-color: var(--note-color-hl);
mask-image: var(--note-icon);
}
dl.see dt::before {
background-color: var(--seealso-color-hl);
mask-image: var(--seealso-icon);
}
dl.remark dt::before {
background-color: var(--remark-color-hl);
mask-image: var(--remark-icon);
}
dl.warning dt::before {
background-color: var(--warning-color-hl);
mask-image: var(--warning-icon);
}
dl.deprecated dt::before {
background-color: var(--deprecated-color-hl);
mask-image: var(--deprecated-icon);
}
dl.note dt::before,
dl.see dt::before,
dl.warning dt::before,
dl.remark dt::before,
dl.deprecated dt::before {
vertical-align: middle;
background-repeat: no-repeat;
content: "";
display: inline-block;
height: 2em;
width: 2em;
margin-right: 0.25rem;
}
dl.note dt,
dl.see dt,
dl.warning dt,
dl.remark dt,
dl.deprecated dt {
margin-top: -0.35em;
margin-bottom: 0.5em;
}

/* icon SVG data */
*:root {
--note-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M200-200h57l391-391-57-57-391 391v57Zm-80 80v-170l528-527q12-11 26.5-17t30.5-6q16 0 31 6t26 18l55 56q12 11 17.5 26t5.5 30q0 16-5.5 30.5T817-647L290-120H120Zm640-584-56-56 56 56Zm-141 85-28-29 57 57-29-28Z"/></svg>');
--seealso-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M480-320q75 0 127.5-52.5T660-500q0-75-52.5-127.5T480-680q-75 0-127.5 52.5T300-500q0 75 52.5 127.5T480-320Zm0-72q-45 0-76.5-31.5T372-500q0-45 31.5-76.5T480-608q45 0 76.5 31.5T588-500q0 45-31.5 76.5T480-392Zm0 192q-146 0-266-81.5T40-500q54-137 174-218.5T480-800q146 0 266 81.5T920-500q-54 137-174 218.5T480-200Zm0-300Zm0 220q113 0 207.5-59.5T832-500q-50-101-144.5-160.5T480-720q-113 0-207.5 59.5T128-500q50 101 144.5 160.5T480-280Z"/></svg>');
--warning-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="m40-120 440-760 440 760H40Zm138-80h604L480-720 178-200Zm302-40q17 0 28.5-11.5T520-280q0-17-11.5-28.5T480-320q-17 0-28.5 11.5T440-280q0 17 11.5 28.5T480-240Zm-40-120h80v-200h-80v200Zm40-100Z"/></svg>');
--remark-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M382-240 154-468l57-57 171 171 367-367 57 57-424 424Z"/></svg>');
--deprecated-icon: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path d="M280-120q-33 0-56.5-23.5T200-200v-520h-40v-80h200v-40h240v40h200v80h-40v520q0 33-23.5 56.5T680-120H280Zm400-600H280v520h400v-520ZM360-280h80v-360h-80v360Zm160 0h80v-360h-80v360ZM280-720v520-520Z"/></svg>');
}

/* color overrides */
html {
/* light theme CSS variables */
--note-color-bg: hsla(47.6, 77.3%, 91.4%, 65%);
--warning-color-bg: hsla(6.8, 75.9%, 88.6%, 65%);
--deprecated-color-bg: hsla(205.7, 22.6%, 93.9%, 65%);
--seealso-color-bg: hsla(215, 76%, 89%, 65%);
--seealso-color-hl: hsl(215, 98%, 48%);
--remark-color-bg: hsla(133, 75%, 89%, 65%);
--remark-color-hl: hsl(133, 98.9%, 35.3%);
}

html.dark-mode {
/* dark theme CSS variables */
--note-color-bg: hsla(45.8, 87.3%, 12.4%, 65%);
--warning-color-bg: hsla(5.2, 33.3%, 13.5%, 65%);
--deprecated-color-bg: hsla(221.5, 12.4%, 20.6%, 65%);
--seealso-color-bg: hsla(215, 33%, 14%, 0.65);
--seealso-color-hl: hsl(215, 98%, 48%);
--remark-color-bg: hsla(133, 32%, 14%, 65%);
--remark-color-hl: hsl(133, 98%, 48%);
}
2 changes: 1 addition & 1 deletion docs/general_usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

1. **Static Network** (No Mesh)

RF24Network can be configured manually, with a static design. RF24Mesh is not used at all. See [Network addressing](http://nRF24.github.io/RF24Network/md_docs_addressing.html)
RF24Network can be configured manually, with a static design. RF24Mesh is not used at all. See [Network addressing](http://nRF24.github.io/RF24Network/md_docs_2addressing.html)
2. **Static Network w/Dynamic Assignment**

RF24Mesh is only used to acquire an address on startup. Nodes are generally expected to remain stationary. Changes to
Expand Down
4 changes: 2 additions & 2 deletions docs/main_page.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,8 +80,8 @@ multi-node radio network.
## How to learn more
- Try it out!
- [Setup and Configuration](md_docs_setup_config.html)
- [Usage & Overview](md_docs_general_usage.html)
- [Setup and Configuration](setup_config.md)
- [Usage & Overview](general_usage.md)
- [RF24Mesh Class Documentation](classRF24Mesh.html)
- [RF24 Network Class Documentation](http://nRF24.github.io/RF24Network/)
- [RF24Ethernet: TCP/IP based Mesh over RF24](http://nRF24.github.io/RF24Ethernet/)
Expand Down
8 changes: 4 additions & 4 deletions docs/setup_config.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,10 @@ connected together.
2. Configure and test the hardware using examples from RF24 and RF24Network prior to attempting to use RF24Mesh
- In Arduino IDE
- File > Examples > RF24 > GettingStarted
@see [Arduino Support page](http://nRF24.github.io/RF24/md_docs_arduino.html)
@see [Arduino Support page](http://nRF24.github.io/RF24/md_docs_2arduino.html)
- For a Raspberry Pi
- An installer is provided: [Linux Installation](http://nRF24.github.io/RF24/md_docs_linux_install.html)
@see [General Linux/RPi setup and configuration page](http://nRF24.github.io/RF24/md_docs_rpi_general.html)
- An installer is provided: [Linux Installation](http://nRF24.github.io/RF24/md_docs_2linux__install.html)
@see [General Linux/RPi setup and configuration page](http://nRF24.github.io/RF24/md_docs_2rpi__general.html)
3. Once testing is complete:
- In Arduino IDE
- File > Examples > RF24Mesh > RF24Mesh_Example
Expand Down Expand Up @@ -65,4 +65,4 @@ The @ref MESH_MAX_CHILDREN option restricts the maximum number of child nodes/no

The MESH_NOMASTER macro optionally reduces program space and memory usage. Can be used on any node except for the master (nodeID 0)

@see [General Usage](md_docs_general_usage.html) for information on how to work with the mesh once connected
@see [General Usage](general_usage.md) for information on how to work with the mesh once connected

0 comments on commit 7c30deb

Please sign in to comment.