jothepro / doxygen-awesome-css

Custom CSS theme for doxygen html-documentation with lots of customization parameters.
https://jothepro.github.io/doxygen-awesome-css/
MIT License
1.05k stars 118 forks source link

Interactive TOC not working #157

Closed ReenigneArcher closed 2 months ago

ReenigneArcher commented 3 months ago

I'm not sure if I'm doing something wrong, but I can't seem to get the Interactive TOC working... other extensions are working fine though.

Doxyfile

DOXYFILE_ENCODING = UTF-8

# doxygen-awesome-css
HTML_COLORSTYLE = LIGHT  # required with Doxygen >= 1.9.5
HTML_COLORSTYLE_HUE = 209
HTML_COLORSTYLE_SAT = 255
HTML_COLORSTYLE_GAMMA = 113
HTML_COPY_CLIPBOARD = NO  # required for Doxygen >= 1.10.0
HTML_EXTRA_FILES = ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js
HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-paragraph-link.js
HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-interactive-toc.js
HTML_EXTRA_FILES += ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome-tabs.js
HTML_EXTRA_STYLESHEET = ../third-party/doxyconfig/doxygen-awesome-css/doxygen-awesome.css
HTML_HEADER = header-doxyconfig.html

# custom aliases
ALIASES = ""
ALIASES += "examples=^^**Examples**^^@code{.cpp}"
ALIASES += "examples_end=@endcode^^"
# fontawsome
ALIASES += "fa_icon{1}=<i class=\"\1\"></i>"
# admonitions
ALIASES += "_admonition{4|}=<dl class=\"\2\"><dt>@fa_icon{\3} \1</dt><dd>\4</dd></dl>"
# see: https://jothepro.github.io/doxygen-awesome-css/class_my_library_1_1_example.html#autotoc_md6
ALIASES += "admonition{2|}=@_admonition{\1 | todo | fa-solid fa-bars | \2}"
ALIASES += "attention{1}=@_admonition{Attention | bug | fa-solid fa-triangle-exclamation | \1}"
ALIASES += "caution{1}=@_admonition{Caution | section warning | fa-solid fa-triangle-exclamation | \1}"
ALIASES += "danger{1}=@_admonition{Danger | bug | fa-solid fa-circle-exclamation | \1}"
ALIASES += "error{1}=@_admonition{Error | bug | fa-solid fa-circle-xmark | \1}"
ALIASES += "hint{1}=@_admonition{Hint | section pre | fa-solid fa-circle-question | \1}"
ALIASES += "important{1}=@_admonition{Important | todo | fa-solid fa-fire | \1}"
ALIASES += "note{1}=@_admonition{Note | section note | fa-solid fa-pencil | \1}"
ALIASES += "seealso{1}=@_admonition{See also | section note | fa-solid fa-circle-info | \1}"
ALIASES += "tip{1}=@_admonition{Tip | section pre | fa-solid fa-circle-info | \1}"
ALIASES += "todo{1}=@_admonition{TODO | section deprecated | fa-solid fa-pencil | \1}"
ALIASES += "warning{1}=@_admonition{Warning | section warning | fa-solid fa-triangle-exclamation | \1}"
# tabs
# see: https://github.com/jothepro/doxygen-awesome-css/discussions/146
ALIASES += tab{2|}="@htmlonly<li><b class=\"tab-title\">@endhtmlonly^^\1^^@htmlonly</b>@endhtmlonly^^\2^^@htmlonly</li>@endhtmlonly"
ALIASES += tabs{1}="@htmlonly<div class=\"tabbed\"><ul>@endhtmlonly^^\1^^@htmlonly</ul></div><br>@endhtmlonly"
# markers
ALIASES += red{1}="<span style=\"color:red\">\1</span>"
ALIASES += blue{1}="<span style=\"color:blue\">\1</span>"
ALIASES += green{1}="<span style=\"color:green\">\1</span>"
ALIASES += yellow{1}="<span style=\"color:yellow\">\1</span>"
# expander
ALIASES += expander{2|}="@htmlonly<details><summary>^^\1^^</summary><div>@endhtmlonly^^\2^^@htmlonly</div></details>@endhtmlonly"

# common predefined
PREDEFINED = DOXYGEN
PREDEFINED += __APPLE__
PREDEFINED += linux
PREDEFINED += __linux
PREDEFINED += __linux__
PREDEFINED += __MACH__
PREDEFINED += _WIN32

# general settings
CASE_SENSE_NAMES = YES
CREATE_SUBDIRS = NO
DISABLE_INDEX = NO
DOCBOOK_OUTPUT = docbook
DOT_IMAGE_FORMAT = svg
DOT_NUM_THREADS = 1
EXTRACT_ALL = NO
FULL_SIDEBAR = NO
GENERATE_HTML = YES
GENERATE_LATEX = NO
GENERATE_TREEVIEW = YES
GENERATE_XML = NO
HAVE_DOT = YES
HTML_OUTPUT = html
INTERACTIVE_SVG = YES
LATEX_OUTPUT = latex
MACRO_EXPANSION = YES
MAN_OUTPUT = man
MARKDOWN_ID_STYLE = GITHUB
MARKDOWN_SUPPORT = YES
NUM_PROC_THREADS = 1
PROJECT_NUMBER = $(READTHEDOCS_VERSION)
OUTPUT_DIRECTORY = $(READTHEDOCS_OUTPUT)
RECURSIVE = YES
RTF_OUTPUT = rtf
SORT_BRIEF_DOCS = YES
STRIP_FROM_INC_PATH = ../
STRIP_FROM_PATH = ../
WARN_AS_ERROR = FAIL_ON_WARNINGS
WARN_IF_DOC_ERROR = YES
WARN_IF_INCOMPLETE_DOC = YES
WARN_IF_UNDOC_ENUM_VAL = YES
WARN_IF_UNDOCUMENTED = YES
WARN_NO_PARAMDOC = YES
WARNINGS = YES
XML_OUTPUT = xml

# project metadata
DOCSET_BUNDLE_ID = dev.lizardbyte.Sunshine
DOCSET_PUBLISHER_ID = dev.lizardbyte.Sunshine.documentation
PROJECT_BRIEF = "Self-hosted game stream host for Moonlight."
PROJECT_ICON = ../sunshine.ico
PROJECT_LOGO = ../sunshine.png
PROJECT_NAME = Sunshine

# project specific settings
DOT_GRAPH_MAX_NODES = 60
IMAGE_PATH = ../docs/images
INCLUDE_PATH = ../third-party/build-deps/ffmpeg/Linux-x86_64/include/
PREDEFINED += SUNSHINE_BUILD_WAYLAND
PREDEFINED += SUNSHINE_TRAY=1

# TODO: Enable this when we have complete documentation
WARN_IF_UNDOCUMENTED = NO

# files and directories to process
USE_MDFILE_AS_MAINPAGE = ../README.md
INPUT = ../README.md \
        getting_started.md \
        changelog.md \
        ../DOCKER_README.md \
        third_party_packages.md \
        gamestream_migration.md \
        legal.md \
        configuration.md \
        app_examples.md \
        guides.md \
        performance_tuning.md \
        troubleshooting.md \
        building.md \
        contributing.md \
        ../third-party/doxyconfig/docs/source_code.md \
        ../src

header-doxyconfig.html

<!-- HTML header for doxygen 1.10.0-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen $doxygenversion"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
<link rel="icon" href="$relpath^$projecticon" type="image/x-icon" />
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
<!--BEGIN DISABLE_INDEX-->
<!--BEGIN FULL_SIDEBAR-->
<script type="text/javascript">var page_layout=1;</script>
<!--END FULL_SIDEBAR-->
<!--END DISABLE_INDEX-->
<script type="text/javascript" src="$relpath^jquery.js"></script>
<script type="text/javascript" src="$relpath^dynsections.js"></script>
$treeview
$search
$mathjax
$darkmode
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
$extrastylesheet

<!--FONTAWESOME START-->
<link href="$relpath^assets/fontawesome/css/all.min.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="$relpath^assets/fontawesome/js/all.min.js"></script>
<!--FONTAWESOME END-->

<!--DOXYGEN-AWESOME START-->
<script type="text/javascript" src="$relpath^doxygen-awesome-darkmode-toggle.js"></script>
<script type="text/javascript">
  DoxygenAwesomeDarkModeToggle.init()
</script>
<script type="text/javascript" src="$relpath^doxygen-awesome-fragment-copy-button.js"></script>
<script type="text/javascript">
  DoxygenAwesomeFragmentCopyButton.init()
</script>
<script type="text/javascript" src="$relpath^doxygen-awesome-paragraph-link.js"></script>
<script type="text/javascript">
  DoxygenAwesomeParagraphLink.init()
</script>
<script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
<script type="text/javascript">
  DoxygenAwesomeInteractiveToc.init()
</script>
<script type="text/javascript" src="$relpath^doxygen-awesome-tabs.js"></script>
<script type="text/javascript">
  DoxygenAwesomeTabs.init()
</script>
<!--DOXYGEN-AWESOME END-->
</head>
<body>
<!--BEGIN DISABLE_INDEX-->
  <!--BEGIN FULL_SIDEBAR-->
<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
  <!--END FULL_SIDEBAR-->
<!--END DISABLE_INDEX-->

<div id="top"><!-- do not remove this div, it is closed by doxygen! -->

<!--BEGIN TITLEAREA-->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <!--BEGIN PROJECT_LOGO-->
  <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"$logosize/></td>
  <!--END PROJECT_LOGO-->
  <!--BEGIN PROJECT_NAME-->
  <td id="projectalign">
   <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
   </div>
   <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
  </td>
  <!--END PROJECT_NAME-->
  <!--BEGIN !PROJECT_NAME-->
   <!--BEGIN PROJECT_BRIEF-->
    <td>
    <div id="projectbrief">$projectbrief</div>
    </td>
   <!--END PROJECT_BRIEF-->
  <!--END !PROJECT_NAME-->
  <!--BEGIN DISABLE_INDEX-->
   <!--BEGIN SEARCHENGINE-->
     <!--BEGIN !FULL_SIDEBAR-->
    <td>$searchbox</td>
     <!--END !FULL_SIDEBAR-->
   <!--END SEARCHENGINE-->
  <!--END DISABLE_INDEX-->
 </tr>
  <!--BEGIN SEARCHENGINE-->
   <!--BEGIN FULL_SIDEBAR-->
   <tr><td colspan="2">$searchbox</td></tr>
   <!--END FULL_SIDEBAR-->
  <!--END SEARCHENGINE-->
 </tbody>
</table>
</div>
<!--END TITLEAREA-->
<!-- end header part -->

The javascript is in the correct location: https://lizardbyte--2932.org.readthedocs.build/projects/sunshine/en/2932/doxygen-awesome-interactive-toc.js

And the result: https://lizardbyte--2932.org.readthedocs.build/projects/sunshine/en/2932/index.html

image

I tried in both Firefox and Chrome. Did I miss something in the configuration?

jothepro commented 2 months ago

It seems to me like you did not include [TOC] or \tableofcontents in the document? The interactive TOC will only work when there is a TOC available on the page.

ReenigneArcher commented 2 months ago

Thank you, I will give that a try.

ReenigneArcher commented 2 months ago

So, this works, but I have one issue. I'm not sure if this can be solved via doxygen-awesome-css or if it's a doxygen issue.

I have a page where the headers are URLs. This isn't too pretty in the interactive TOC.

https://docs.lizardbyte.dev/projects/sunshine/en/master/md_docs_2configuration.html

Any ideas on how this can be solved?

jothepro commented 2 months ago

No, unfortunately I am not aware of a workaround for that. Why are the headers URLs?

ReenigneArcher commented 2 months ago

They document the settings of our application, the user can click on the URL in the docs and it will take them to the location in our Web UI where they can change the setting.

I can probably come up with another way to do this though.