Yesterday I added some simpler variants that keeps the descriptive text in verbatim boxes:
dgeqp3.f becomes
dgeqp3.html.
The result looks less nice but is easier to realize. I
converted all of LAPACK 3.3.1 and only in a few cases some additional work would be required. For example in
cgbequb.html still has a 'IMPLICIT NONE' artifact ...
CyLith wrote:Oh holy hell that's 100x better than what it is now! For some reason, they decided to add tons of awful markup so that they could generate the equally terrible online docs.
What I don't understand is why they actually included the markups for doxygen into the LAPACK source code. It would not be difficult to automatically generate a file like
lapack-3.4.2/dgeqp3.f from a
lapack-3.3.1/dgeqp3.f. This could be achieved through a small Perl script and easily integrated into the tool chain... As an alternative I consider to write a Perl script that reverses the process, so that I can have a local copy without classic LAPACK comments.
CyLith wrote:Do you have scripts available for your conversion process? I'm working on a header-only reimplementation of the basic (and imho more important) parts of lapack in C++, and I'd love to generate nice documentation without seriously messing up all the code.
I created the LAPACK documentation with
DocTool which I wrote for my own Project
FLENS. I will upload the code for extracting the LAPACK comments in the next days.
As I wrote DocTool mainly for myself I did not spend too much effort on documenting itself. However, you might get an idea by looking at some examples:
1.) For creating tutorials I adopted some ideas from
Literate Programming. That means documentation, source code, compile instructions, post processing, etc. can all be put into a single file. When the documentation gets created the code actually get compiled and executed:
2.) As embedding the complete source code into the documentation sometimes is cumbersome you also can use an import directive:
3) Here an example that contains links, lists, tables, lists in tables, ...
4) I am using libclang for parsing C++ code and extracting function stubs, methods, ... from C++ source files.
- So from a C++ file like gbmatrix.h
- I create these stubs gbmatrix.doc
- Without further editing the default still looks pretty poor: gbmatrix.html. The boxes are clickable and let you jump to the corresponding position in the header file.
- Here an example where already some additional text was added: densevector.html
- And here an example for documenting functions: lapack/ge/trf
5) Cross-Referencing is pretty easy due to libclang. If you look a source code listings like
lapack-gelsy.cc you see that some words a (dotted) underlined. If you click these word you jump to their definition. This includes variables, functions, classes,... If an overload resolution is not possible at compile time the words is underlined red and you get a list of (clickable) possibilities.
