Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation #35

Open
LaG1924 opened this issue Apr 11, 2019 · 2 comments
Open

Documentation #35

LaG1924 opened this issue Apr 11, 2019 · 2 comments

Comments

@LaG1924
Copy link
Owner

LaG1924 commented Apr 11, 2019

There is minor problem with documentation for code. It's missing.
Doxygen isn't looks good for html-documentation. Alternatives?

@MrDullDev
Copy link

MrDullDev commented Jan 21, 2021

I am not sure what do you mean by "doesn't look good"(since doxygen has a lot of downfalls apart from default looks), but assuming you mean esthetics i would recomend sphinx(it was originally python only, but nowadays it supports quite a variety of languages thanks to extensions). Sphinx is quite mature framework(i mean they are even a lot of big projects that use them like llvm and cmake) and it has a lot of themes to choose from on top of that, you can see them here https://www.sphinx-doc.org/en/master/examples.html . Although Sphinx uses Breathe to make use of doxygen generated xml(fun fact doxygen oficial documentation actually mentions it https://www.doxygen.nl/manual/customize.html#xmlgenerator), so it is not exactly standalone solution

Also there is good table of document generators on wiki https://en.wikipedia.org/wiki/Comparison_of_documentation_generators .

There is actually a thing deserving a honorable mention standardese , it is work in progress documentation generator that aims to be next-gen doxygen. As far as i am concerned this page was generated with it https://standardese.github.io/ , but i am not sure since i used it quite a while back and never messed with the visuals(aka i generated only very plane looking html). I mentioned it here since it seems promising

@LaG1924
Copy link
Owner Author

LaG1924 commented Mar 14, 2021

I believe Standardese is a good thing. But this project is still too new, so I would not use it for now (and it lacks some important features that doxygen has).
And sphinx looks good too.

But, lately, my attitude towards documentation has changed. In the last project, I wrote only doxygen-style comments for classes, and together with the support from the IDE, this turned out to be enough so that other programmers did not experience difficulties.
Separate HTML documentation is required only for libraries or something similar. For End-User projects, only a small guide on how to use it will be enough (in the case of AC, just a list of differences from the original MC should be enough).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants