search

Project-OSRM / osrm-backend

Open Source Routing Machine - C++ backend
http://map.project-osrm.org
BSD 2-Clause "Simplified" License
6.46k stars 3.42k forks source link

OSRM doxygen theme for C++ docs #1706

Closed amyleew closed 7 years ago

amyleew commented 9 years ago

Per https://github.com/Project-OSRM/osrm-backend/issues/1577, https://github.com/Project-OSRM/osrm-backend/issues/1434, https://github.com/Project-OSRM/osrm-backend/pull/1666 + chat w/ @daniel-j-h, we need internal facing documentation for our OSRM API / library exposing all internal functions, classes, algorithms and datastructures.

Doxygen default

libosmium publishes docs based on default doxygen theme:

In general, massive amounts of information is condensed onto small space with a 90s look.

image

Modern design

The goal is a developer-friendly, easy to use internal docs built with Doxygen. Not sure how complex this will be, so @daniel-j-h and I want to spec this out and decide on what's feasible and most efficient.

Quick stab at layout with Project OSRM logo and colors:

image

Next steps

Discuss specific needs for a modern, readable OSRM doxygen theme @danpat @TheMarex @morganherlocker. We can work out a mostly OSRM independent theme first, so other C++ projects like libosmium can re-use it by just switching out a few html/css/js files.

daniel-j-h commented 9 years ago

/cc @joto you may be interested in this, too: if we create a developer friendly and modern theme, I guess you could switch that in for libosmium by just using the custom style file.

joto commented 9 years ago

I tried creating a style at some time that would better fit into the rest of the libosmium web site and gave up on it. It wasn't as easy as I thought to get everything fit together well. But if somebody else wants to do that, I am all for it. The standard theme isn't that great. I would vote though for a general "updated look" though not tied too much to a specific project, because that way it can be re-used easily and we don't have to update it every time the projects web site changes. And getting two web sites generated by totally different means to have matching layouts etc. is difficult anyway.

daniel-j-h commented 9 years ago

Yes, the goal should be to provide a mostly un-branded theme that is developer friendly and great to use on every project out there. Project specifics can come in later in small local adjustments.

This could live in its own repository, maybe at mapbox/doxygen-modern-theme or something like that.

Now what interests me is the following.

What are the possibilities regarding customization? I think we can provide custom css and js files and custom header and footer html templates. Is this enough to make major adjustments or is it only good for some rather local changes such as spacings or color palettes as an example?

Leaving the default doxygen theme aside and starting from a blank page, what does a great automatically generated documentation has to provide for you?

TheMarex commented 9 years ago

Leaving the default doxygen theme aside and starting from a blank page, what does a great automatically generated documentation has to provide for you?

In my experience any documentation that requires me to click through multiple levels of page hierarchy is not really useful. Having something like the Leaflet reference would be great. Just a single page with a minimal clutter. Not sure if that is actually possible with doxygen.

TheMarex commented 7 years ago

We now have a single page documentation thanks to docbox.