MkDocs and Documentation updates

[Hecatron]

Hi, I've recently done a bit of a re-write on the docs

The content is still in markdown but what I've also included is some python scripts that use mkdocs to render the docs into a static web page Github has a feature called github pages where if you publish static html content to a branch called "gh-pages" in the repo it's served out has a web page for the project

In theory if the branch existed it would appear under the link of - http://ddobrev.github.io/QtSharp I've put a preview of what it would look like on my fork here - http://grbd.github.io/QtSharp

I'm not sure if you want to use mkdocs for this sort of thing, the python scripts for the setup are just a copy / paste from something I've used before the theme is bootswatch / bootstrap / cyborg although there are also other colour schemes as well there's a couple of custom theme files in there to add in Edit and Doxygen buttons to the title for the bootswatch themes

There's also some doxygen files in there as well for generating an api reference as part of the site However at the moment it's only picking up on the QtSharp.CLI apps and libs, not the generated QtSharp libs I think the doxyfile needs a bit of tweaking to avoid picking up too much The details on how to run the scripts should be under Docs\MkDocs\Readme.md

"build.py build_doxygen" - generate Doxygen content, best to run after changing the menu content / page list to update the header for it. "build.py serve" - preview the site via a local link of http://127.0.0.1:8000 which auto refreshes on content change. "build.py publish" - generate the site and auto push it to the gh-pages branch

[ddobrev]

@grbd thank you very much for your work. I used to generate DOxygen-based documentation for the predecessor of Qt#, Qyoto, and it worked really well. In fact, I still keep a configuration file for DOxygen which handles Qt-specific details such as ignoring the initial "Q" when indexing and searching. I would be glad to send it to you in case you find it useful. The documentation in your pull is much better. I think you can make it even better by entirely dropping the part about getting C++#. It now has a NuGet at https://www.nuget.org/packages/CppSharp/ which Qt# uses. It's true that the NuGet only works on Windows 64-bit for now but building Clang and then C++# is too complicated and would only confuse and therefore repel users. Besides, I am going to extend the NuGet with the remaining OS-es in the near future.

[Hecatron]

Thanks for the info if you can send the Doxyfile across that would be great, I tried initially picking up the content from the generated cs files from Qt# but it seemed to take forever to render and picked up a lot of _internal stuff

The reason for including the Cpp# stuff was to try and encourage other users to get involved with the development. What I think I'll do is remove the Cpp# stuff from the generated mkdocs, but just have a link there to a directory on the git repo with any development related docs for anyone that way inclined. It's basically just a list of tweaks or changes I had to make to get the latest master version to work which would only be useful for anyone wanting to devlop the code instead of just use it, but that doesn't need to be on the main mkdocs rendered output. Also I'll add in a link to the releases page for downloads

One thing you might want to consider for other Os's btw is the use of Visual Studio 2017, they've changed the csproj structure to be cross platform / can be user generated / no longer needs magic guid's. There's .Net standard for libraries that will work between frameworks, and .Net core for the next generation framework. Although they may be missing needed API's at this point

[ddobrev]

Doxyfile.zip

This is the DOxygen configuration file. You'll need to edit it a little because it's still named after Qyoto and its version, and has a path from my old machine. But you can do that with the DOxygen GUI so it should pose little effort. Your idea about just mentioning C++# is excellent and completely adequate. I didn't know about this feature of VS 2017, I'll definitely consider switching. Thank you for mentioning it.

[Hecatron]

Okay, I've now made some changes and tweaks to the layout / css / Doxygen files etc I've disabled the diagrams by setting HAVE_DOT, CLASS_DIAGRAMS to no this was because the number of files generated was getting quite large

If you want I can try and re-enable the diagrams, I'd probably set create_subdirs to yes in that case let me know what you think, if there should be any changes etc The commit id should now be updated with the latest changes

Examples: https://grbd.github.io/QtSharp/doxygen/namespaces.html - namespaces https://grbd.github.io/QtSharp/doxygen/annotated.html - class list https://grbd.github.io/QtSharp/doxygen/class_q_label.html - Qlabel

Note if you want to deploy this to your own repo via github pages then you'll need the bits installed to generate the site This should be listed in the MkDocs/Readme.md

[ddobrev]

@grbd thank you once again for your work. The documentation looks really nice. I would like us to enter a discussion because I have some questions which might lead to suggestions for improvement.

1. This is purely subjective but is there any reason you dislike the default look of DOxygen? I used it for the old Qyoto documentation you can still see at https://api.kde.org/qyoto-api/class_qt_gui_1_1_q_abstract_button.html and I personally find it easier to read. Please browse it a little and tell me what you think;
2. Diagrams are really nice to have. Besides, I don't quite understand what the problem with large files is. After all, the documentation for Qt# is going to be generated, not contained, in a similar manner to the source code;
3. I would like to have some more details about why you decided to use MkDocs instead of the regular DOxygen. I can see you had to write quite a little Python, HTML and CSS by hand while I used to just open DOxygen, load my configuration (which I hope you find useful) and the paths to the generated source and I got the documentation package complete with diagrams. Now, I used the GUI but I know the same result can be achieved with their command-line tool. My point is that I didn't need to write and maintain any code at all. Unless I misread your pull, you have to write code yourself which I see as a disadvantage unless MkDocs has some significant advantages I am not aware of.

[Hecatron]

1. For Doxygen I can try and move it back to the original theme if you'd like The only reason I used the MkDoc css for it was purely aesthetics. It's more of a personal preference thing so I'll try and see if I can put it back to the original theme but maintain the navigation bar at the top at the same time

2. Basically it was just taking a long time to generate that's all The files individually wern't that large, it's just that there was a lot of them at the moment there's about 10,000 for the file count, I think that jumps up to about 40,000 with images Now that I've already filtered some stuff out I'll try and re-add them back in again

3. MkDocs is mostly for turning markdown files into static html with menu's and themes and search The Doxygen part of it is really just a hacky addon. The benifit would probably be if there was a lot more markdown pages to maintain such as code examples or snippets. Also it generates a static based search index. This is an example of one I've done that has a lot more pages and menu's - http://hacmanchester.github.io/Tools.Shapeoko2/

[ddobrev]

@grbd thank you for your fast reply. 1. and 2. are now pretty much resolved. About 3., I could not really understand what justifies so much code compared to DOxygen requiring none. Perhaps in order to explain it better to me, you could examine the internal structure of the old Qyoto documentation - http://download.kde.org/stable/csharp-qt/4.0.6/docs/CSharpQt-Documentation-4.0.6.tar.gz - and compare it to the one MkDocs generates. For example, the MkDocs package might be much smaller or faster.

[Hecatron]

From the looks of things that file is purely Doxygen without any other non API pages such as the guides on building stuff etc. You might be able to get Doxygen to render markdown files I'm not sure.

The doxygen content that I'm using at the moment is a direct output from doxygen, the css has just been tweaked a bit to use a bootstrap theme and to add in a navigation menu, so it looks different but it's actually the same thing. Mkdocs is just a wrapper around it providing the non Doxygen content such as the step by step guides, any other markdown pages to be inserted etc

For point 3 there isn't really any code needed, it's really just a convenience

For the build.py under QtSharp.grbd\Docs\MkDocs just cleans the directory, then runs the correct commands with the correct options to build the site in different ways because I can never remember the correct command line switches. All the of the actual work is done via the mkdocs python stuff which isn't visible (installed via pip) and the mkdocs.yml file which acts as a bunch of settings / list of site pages. You could scrap the build.py file and run the mkdocs command directly, but since you still need python installed anyway it just makes life harder

The theme directory under MkDocs\theme is just a couple of tweaks to the menu header Any files located here override the default bootswatch themes installed via pip.

The build.py under Docs\Doxygen is a bit more fancy, it's running doxygen with the correct options the same as the other one. But it's also extracting the top menu navigation bar and trying to fit it into the header of the doxygen template before doxygen runs. You could remove this if you wanted to. It just means there won't be a menu list of other non Doxygen related pages, probably just a single link back to the root of the site

[tritao]

@grbd Looks pretty good, how hard would it be to re-use the same setup for CppSharp?

[Hecatron]

It should be pretty easy to do for CppSharp Since we'll be using the default doxygen theme for QtSharp I'm thinking of switching the color scheme to a white / light blue to match https://bootswatch.com/ assuming the mkdocs part is still used

[ddobrev]

@grbd thank you for the clarification. I cannot tell from now if this is going to remain in this form because I have many other priorities over documentation but I'd rather merge it than let it rot. So please just remove the parts about building LLVM and C++# and I'll merge this.

[ddobrev]

By the way, @tritao has an excellent point. There's actually nothing Qt-specific in this documentation except perhaps a user-provided configuration file for DOxygen so C++# could be extended to also generate a documentation package from the generated C# code.

[Hecatron]

If there's interest for something similar for CppSharp, I'll move those related bits to a separate pull request for that one. There's still markdown files in this pull request that relate to which version of Qt to use / building QtSharp / running tests etc so I'll leave those in. But I'll look at altering the theme for Doxygen back to it's original look

[Hecatron]

I'm going to close this for now and come back to it later I'm currently looking into using scons as a wrapper for mkdocs, and for using scons for .net core projects