From 070b1a17dd32a673fd96e645d47dd0ca3bf764c6 Mon Sep 17 00:00:00 2001 From: kat Date: Mon, 17 Oct 2022 12:37:02 -0400 Subject: [C++ docs] Several fixes, improvements, additions, and general cleanup - Sort documentation into groups (aka. modules) - Add DataRenderer, BinaryView, InstructionTextToken, Others docs - Fixes stylesheet for documentation website - New 'Deprecated' section listing deprecated items - Re-add 'Files' listing - Add a 'Main page' and restructure the navbar --- api-docs/cppdocs/Doxyfile | 2 +- api-docs/cppdocs/DoxygenLayout.xml | 12 ++++++++---- api-docs/cppdocs/README.md | 14 +++++++------- api-docs/cppdocs/custom.css | 33 ++++++++++++++++++++++++++++----- api-docs/cppdocs/header.html | 4 ++-- 5 files changed, 46 insertions(+), 19 deletions(-) (limited to 'api-docs/cppdocs') diff --git a/api-docs/cppdocs/Doxyfile b/api-docs/cppdocs/Doxyfile index 72a82539..244c3163 100644 --- a/api-docs/cppdocs/Doxyfile +++ b/api-docs/cppdocs/Doxyfile @@ -2147,7 +2147,7 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = +PREDEFINED = DOXYGEN_INCLUDE_MAINPAGE # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/api-docs/cppdocs/DoxygenLayout.xml b/api-docs/cppdocs/DoxygenLayout.xml index f946e233..73a7bfdb 100644 --- a/api-docs/cppdocs/DoxygenLayout.xml +++ b/api-docs/cppdocs/DoxygenLayout.xml @@ -2,7 +2,7 @@ - + @@ -21,12 +21,16 @@ - + + + + + - + @@ -153,7 +157,7 @@ - + diff --git a/api-docs/cppdocs/README.md b/api-docs/cppdocs/README.md index 9a857d17..56412839 100644 --- a/api-docs/cppdocs/README.md +++ b/api-docs/cppdocs/README.md @@ -1,8 +1,8 @@ # CPP Docs -We are currently experimenting with two different document generation systems. You'll see artifacts for both of them in this directory. Currently, the documentation available [online](https://api.binary.ninja/cpp) uses [Doxygen](https://www.doxygen.nl/index.html) but we plan eventually to move to [Breathe](https://breathe.readthedocs.io/en/latest/) / [Sphinx](https://www.sphinx-doc.org/en/master/). +We currently use `doxygen` for our C++ documentation generation. -## Doxygen +> Note: Using anything newer than doxygen 1.9.4 will cause minor issues with the website whenever the selected theme conflicts with the OS/browser light/dark mode selection. Generating documentation with Doxygen couldn't be simpler. Just install it and run: @@ -12,13 +12,13 @@ $ doxygen From this directory. The output will be stored in `html/` +## Installing doxygen -## Breathe/Sphinx +The theme for our documentation works best with doxygen 1.9.0 - 1.9.4 -The requirements are already described in our [documentation](https://docs.binary.ninja/dev/documentation.html). Instead, however simply navigate to this directory and use: +### macOS (Homebrew) ``` -sphinx-build -b html . html/ +wget https://raw.githubusercontent.com/Homebrew/homebrew-core/41828ee36b96e35b63b2a4c8cfc2df2c3728944a/Formula/doxygen.rb` +brew install ./doxygen.rb ``` - -Note that Sphinx will take significantly longer due to some performance issues with breathe and doxygen generated XML. This is the main reason this is not our primary workflow. diff --git a/api-docs/cppdocs/custom.css b/api-docs/cppdocs/custom.css index e977a5b7..11997bbe 100644 --- a/api-docs/cppdocs/custom.css +++ b/api-docs/cppdocs/custom.css @@ -43,13 +43,8 @@ html { --primary-color: #c74433!important; --primary-dark-color: #d0584d !important;; --primary-light-color: #a2382a !important;; - --side-nav-background: #252628 !important; - --side-nav-foreground: #ffffff !important; } -div#projectname { - color: white; -} .paramname { color: var(--primary-light-color); } @@ -72,6 +67,34 @@ input#MSearchField { top: -1px; } +/* Replicating an "undecorated root node" */ + +.children_ul a.index\.html { + display: initial !important; +} + +a.index\.html { + display: none; +} + + +#nav-tree-contents > ul > li > .item { + height: 0px; +} + +/* --- */ + +/* Move the "Deprecated Items" item to the end of the list. */ +#nav-tree-contents > ul > li > ul.children_ul { + margin: 0px; + padding: 0px; + display: flex!important; + flex-direction: column!important; +} +#nav-tree-contents > ul > li > ul > li:nth-of-type(2) { + order: 9999999; +} + /* Basic Mobile functionality fixes */ @media screen and (max-width: 767px) { div#top { diff --git a/api-docs/cppdocs/header.html b/api-docs/cppdocs/header.html index 7d2534eb..cf41aa50 100644 --- a/api-docs/cppdocs/header.html +++ b/api-docs/cppdocs/header.html @@ -45,8 +45,8 @@ $extrastylesheet -
Binary Ninja C++ API $projectnumber -
+ -- cgit v1.3.1