Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/haozeke/doxyyoda

Modern CSS + SCSS Doxygen theme
https://github.com/haozeke/doxyyoda

css documentation doxygen scss theme website

Last synced: 4 days ago
JSON representation

Modern CSS + SCSS Doxygen theme

Awesome Lists containing this project

README 

        
* doxyYoda

#+DOWNLOADED: screenshot @ 2021-03-02 01:34:09

[[file:images/doxyYoda/2021-03-02_01-34-09_screenshot.png]]



A theme for [[http://doxygen.nl/][Doxygen]]. The **only** theme to use [[https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout][CSS Grid]] and [[https://sass-lang.com/guide][Sass]]. Also uses MathJax 3. Part of my ~yoda~ series of tools.

** Why?

Have you seen ~doxygen~ HTML? To go from:

#+DOWNLOADED: screenshot @ 2021-03-02 00:51:00

[[file:images/why/2021-03-02_00-51-00_screenshot.png]]

To:

#+DOWNLOADED: screenshot @ 2021-03-02 00:51:40

[[file:images/why/2021-03-02_00-51-40_screenshot.png]]

*** But... [x] does this

- Doxyrest :: Does not allow embedding source inline (see above), ~doxyrest~ just doesn't capture the same level of information

- Exhale / Breathe :: Can't even display source code, inline or otherwise

Honestly, nothing captures C++ like Doxygen. Nothing. So inspite of the weird JS cruft its best not to fight it (*cough* [[https://foonathan.net/2019/11/standardese-post-mortem/][Standardese]]). This is it.

- m.css :: is actually very good; used it for [[https://dseams.info][d-SEAMS]]; but this is better for me, and will migrate the rest of my projects later

*** Features

- CSS Grid layout

  - With Sass

- MathJax 3

- Foldable inline code

** Usage

Clone the project into the directory with your ~Doxyfile~.

Inside your ~Doxyfile~:

#+begin_src conf

HTML_HEADER            = "doxyYoda/src/html/header.html"

HTML_FOOTER            = "doxyYoda/src/html/footer.html"

HTML_EXTRA_STYLESHEET  = "doxyYoda/src/styles/doxyYoda.css"

LAYOUT_FILE            = "doxyYoda/src/xml/layout.xml"

#+end_src

Or with the release, simply download the ~.tar.gz~ into the directory with the ~Doxyfile~ and:

#+begin_src conf

HTML_HEADER            = "doxyYoda/html/header.html"

HTML_FOOTER            = "doxyYoda/html/footer.html"

HTML_EXTRA_STYLESHEET  = "doxyYoda/css/doxyYoda.min.css"

LAYOUT_FILE            = "doxyYoda/xml/layout.xml"

#+end_src

** How?

- [[https://sass-lang.com/documentation/cli/dart-sass][Dart sass]] is needed to compile the CSS

- The colors are taken from [[https://ethanschoonover.com/solarized/][Solarized Light]] and the [[https://github.com/HaoZeke/hugo-theme-hello-friend-ng-hz/branches][hello-friend-ng-hz]] Hugo theme

- Fonts used are from Google Fonts (and Microsoft)

  - [[https://github.com/microsoft/cascadia-code/][Cascadia]]

  - [[http://vollkorn-typeface.com/][Vollkorn]]

  - [[https://fonts.google.com/specimen/PT+Sans?category=Sans+Serif&preview.text_type=custom][Product Sans]]

- Everything is minfied with [[https://github.com/tdewolff/minify][minify]]

*** Development Workflow?

Thanks for thinking of contributing! The workflow I use for making and tracking changes involves [[https://github.com/filewatcher/filewatcher-cli][filewatcher-cli]] and [[https://wiki.alpinelinux.org/wiki/Darkhttpd][darkhttpd]] along with an example project.

#+begin_src bash

# One

filewatcher -s  '**/*.scss' "sass src/styles/scss/main.scss:src/styles/doxyYoda.css"

# Two

filewatcher -s  '../../symengine/* ./* ../../../../doxyYoda/**/*.{css,html,xml}' "doxygen Doxyfile-prj.cfg"

#+end_src

** Tree View?

Unfortunately, as long as Doxygen keeps shipping silly ~jQuery~ based javascript scripts which write weird resizing logic into the HTML on the fly, tree view isn't very feasible.

*** I really want it!

There are some commented out sections relating to an attempt to work around the jQuery rubbish but it amounts to just rewriting the HTML in place (see commit 07cdb06). Might consider this later.

** Users

- [[https://symengine.org/symengine][SymEngine C++ API documentaion]]

- [[https://docs.dseams.info][d-SEAMS API Documentation]]

- [[https://haozeke.github.io/eigen/][Eigen v3.4.0 (git) Unofficial API Documentation]]

- [[https://atomic-solvers.github.io/featom/][featom API Documentation]]

- [[https://haozeke.github.io/GaussJacobiQuad/][GaussJacobiQuad API Documentation]]

* TODO Tasks

** Add an example in-place

** Better documentation

** Minification / Autoprefixer / Other Goodies

** Over-engineer with Webpack

* Acknowledgments

This project was conceived as part of SymEngine's Google Season of Docs 2020.

* License

[[https://www.apache.org/licenses/LICENSE-2.0.html][Apache version 2]]