Generate Soar programming reference from Doxygen comments and host here

[garfieldnate]

Particularly an SML programming reference would be very helpful, since SWIG ignores Doxygen comments, and Python/Java, etc. developers are mostly flying blind. Whenever I need to understand something about the SML API, I search through Soar's C++ code for the original definition and read the comments there.

[moschmdt]

MkDoxy might be an opportunity but not without drawbacks I assume. MkDoxy this is based on the docs being in the same repository as the source code, but maybe this could be solved by integrating the Soar repository via reference as git submodule or via vcs tool.

[garfieldnate]

MkDoxy looks very cool! Thanks for finding that. I think I'd be happy enough just to have the CI checkout a shallow copy of Soar's source and build from there. It does make local website development more complicated, though, because I don't want to accidentally check in my local Soar source path to a configuration variable in this repo. Perhaps it would be possible to use an environment variable to specify the source location or something.

[moschmdt]

I tried to include the documentation with mkdoxy and added Soar as a git submodule but ran into quite a lot of errors raised by mkdoxy. Using the default Doxygen generator and linking to it might be the easiest way until other projects mature...

[garfieldnate]

Thanks for testing that! Soar as a submodule for that use-case makes sense, since we want the hosted docs to be the last released version. What kinds of errors were you seeing? I would be okay doing a bit of work to send a PR to mkdoxy, but of course if it's a huge hassle we'd have to drop the idea.

[moschmdt]

I tried to directly hook up the existing Kernel.doxygen and SML.doxygen files to the mkdoxy plugin, but had some minor parsing errors, e.g. Doxygen comments are not ignored. Once I got to some temporary xml files that resulted in a tree parsing error in a dependent library I stopped looking any further...Unfortunately, I can't really guess where the origin of the error is (old incompatible Doxygen style comments in C code?/ parsing error in mkdoxy? / parsing error in dependent library?)

[moschmdt]

Just tried to see if I could get mkdoxy to work or figure out where it breaks. I accidentally tried it on my fork of Soar where it just worked?! You can have a look at it at my documentation fork where I just pushed the minimal working version.

I had to disable the macros due to an error (not looked at it any further) and a Doxygen installation is required.

[garfieldnate]

Woohoo! This is starting to look doable. What were the macros errors? I wonder if we could just disable it for these directories. I don't see a specific exclude param for that plugin, but the author is very responsive on GitHub, so we could probably ask about it.

[moschmdt]

What were the macros errors?

INFO    -  [macros] - ERROR # _Macro Syntax Error_

           _File_: `SoarSML/cli__Commands_8h_source.md`

           _Line 32 in Markdown file:_ **unexpected '}'**
           ```markdown
               OptionsData optionsData[] = {{'r', "remove", OPTARG_NONE},
           ```

I assume that the exclude option might be a good idea.