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

Update Sphinx docs to cover the API. #127

Open
HexDecimal opened this issue Aug 25, 2022 · 3 comments
Open

Update Sphinx docs to cover the API. #127

HexDecimal opened this issue Aug 25, 2022 · 3 comments
Assignees
Labels
documentation Documentation needs to be updated. enhancement
Milestone

Comments

@HexDecimal
Copy link
Collaborator

This is probably one of the most important issues right now that the current docs are pretty terrible and people are usually forced to use the old docs or go into the headers for any new API features.

I'm making this issue because I keep forgetting the steps to do this so I need to organize them here.

The main issue is that I'm using the wrong directives most of the time. I'm using the doxygenclass and doxygenfunction directives a lot which makes it really hard to keep the docs up-to-date with the headers, especially when overloads are used. I need to be using the doxygenfile or autodoxygenfile directives instead to document entire header files automatically and only use the more specific directives for special cases.
https://breathe.readthedocs.io/en/latest/directives.html

@HexDecimal HexDecimal added enhancement documentation Documentation needs to be updated. labels Aug 25, 2022
@HexDecimal HexDecimal added this to the libtcod 2.0.0 milestone Aug 25, 2022
@HexDecimal HexDecimal self-assigned this Aug 25, 2022
@HexDecimal
Copy link
Collaborator Author

doxygengroup seems to be the ideal directive for the older docs. This lets me group things nicely without needing to change the overall structure.

@HexDecimal
Copy link
Collaborator Author

Breathe directives are causing conflicts, so I'm looking into using Exhale to extract the docs from the sources instead.

@HexDecimal
Copy link
Collaborator Author

HexDecimal commented Nov 7, 2022

So far all docs that were only in the headers are now in the online docs. However it's mostly auto-generated and there are multiple symbols included which should be removed.

I can't figure out how to effectively use Doxygen groups. In theory this should let me group related functions together on one page of docs but I'm not sure how it works in practice with Breathe/Exhale.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Documentation needs to be updated. enhancement
Projects
None yet
Development

No branches or pull requests

1 participant