Doxygen Documentation

[marcosfpr]

I'm starting to develop the Doxygen documentation for Small. Currently, I've just managed to get the structure done.

For the following steps, I'd fix some issues that may appear on this structure and add new documentation Markdown files to create more documentation as we have in the Futures project.

[alandefreitas]

That's really great! We do need to get Doxygen generation properly here.

Did mkdocs work locally for you? Any questions about this structure?

I'll execute all of that locally this week and send you a review. :)

[marcosfpr]

@alandefreitas I ran locally, and it works fine :-). Of course, there are a lot of things to get done yet, but it's working at least locally.

[alandefreitas]

@alandefreitas I ran locally, and it works fine :-).

Nice. I'm not sure this is mentioned anywhere, but the best way to test and work on it seems to be

mkdocs serve --dirtyreload

The build command is just for CI, where we want the static pages, so we use serve to be able to work on the pages in real time.

--dirty-reload is useful because the references include many pages we don't need to render again when are working on the exposition.

Of course, there are a lot of things to get done yet, but it's working at least locally.

No problem. We just need the basic layout for now.

[alandefreitas]

I made some changes. Currently, I'm facing an error with the References generated documentation. The error message is:

 Exception at Utils.cpp:218 Failed to create directory /my/path/to/small/docs/reference/Classes error -1

All the rest is working fine.

I'm assuming this happens when running doxybook2, right? You probably just need to remove docs/reference before running doxybook2 again.

[marcosfpr]

It looks like this is almost good to go.

We don't need "Doxygen Documentation - Proposed Changes". Just squashing "Doxygen Documentation" or "[FOLD] Doxygen Documentation" should be OK.

The BG color is nice, but we might want to revisit the colors in stylesheets for the code blocks though. They're not easy to read:

The main problem here is I couldn't generate the docs locally either. The failure to create the directory is just a matter of creating the directory locally: matusnovak/doxybook2#40

But then we get

[error] Exception at Doxygen.cpp:210 No <compound> element in file ./xml/index.xml

It seems like the symbols are not going into docs/xml. Something is missing from the Doxyfile. It's output is empty.

One way to debug that independently from the mkdocs toolchain is to temporarily generate the HTML docs:

GENERATE_HTML = YES

in line 31. You should be able to see the reference is empty:

I figured out what had happened. Basically, you did a folder renaming recently, changing the root project of source/* to include/*, and so it was just a question of renaming some stuff in our scripts as well.

Also, about the color scheme, I made this scheme based on the small logo, but I agree that there are things that need to be changed. Working on that as well.

[alandefreitas]

I figured out what had happened. Basically, you did a folder renaming recently, changing the root project of source/* to include/*, and so it was just a question of renaming some stuff in our scripts as well.

Phew

Also, about the color scheme, I made this scheme based on the small logo, but I agree that there are things that need to be changed. Working on that as well.

Yep. We do need a new proper logo on GIMP or something. This was just an SVG template that's been there as a placeholder for longer than it should. I think I opened an issue for that already.

Although the color is circumstantial, this light blue is not that bad. Only the content tabs are kind of hard to read.

[alandefreitas]

Nice. Besides the comments, one thing to notice is you have to rebase on top of develop again. I think the only difference now is that your other PR has been renamed. But you should keep rebasing anyway to ensure your branch is up to date.