Nuklear
Nuklear copied to clipboard
Immediate-Mode-UI
Offer: willing to document
Hellooo 👋 I'm down to document the user facing api of Nuklear I've noted that not all functions are documented and the documentation is split across the wiki and the website ... Hence I would like to bring it all together to something coherent. Hence I'd like to know what efforts are being made towards this to see where I can help or how y'all envision this should be done
Would love some help on the documentation. Two things I can think of...
- The Wiki docs could expand https://github.com/Immediate-Mode-UI/Nuklear/wiki
- The inline documentation could improve too, have been thinking of making a move to Doxygen for the comments
@quadroli do you have any notes already? I'm interested in nk_widget and nk_list_view_begin - these functions are not documented at all and the second one is not used in any example.
I see, I'll pay close attention to those two No, I do not have notes ready just yet
I use doxygen a lot. If you want, I can give the project a quick conversion and get a PR up for some initial feedback. I think moving to something g like doxygen and having the inoine comments sync with the website would help a lot
@awschult002 💯 I second that That would be awesome, @RobLoach would love that too
I'm writing a C++ wrapper library for Nuklear. I'm also using Doxygen. If Nuklear moved to it, I could have one documentation for both libraries in one place. That would be great.
edit - repo link: https://github.com/Xeverous/nukleus
i am starting on the Doxygen stuff now. but i do have some questions on how the group would like to move forward. The existing documentation structure is not exactly how doxygen expects the information to be laid out. That isn't to say that doxygen cannot handle what currently exists; but I think restructuring comments a little bit and moving a lot of the information in nuklear.h into the separate source files would be more beneficial. This, however, would require me to start moving and copying stuff into many of the other source files and could end up creating huge merge conflicts with any existing PRs.
How much change is the project willing to take on for this update? ( i personally think it is worth it). How much change/input does the group want before the initial merge/switch to doxygen? do you want everything to move over with as much change as necessary? or do you want a minimal change right now and slowly start to integrate or migrate?
@quadroli @RobLoach @Xeverous I have kicked off a doxygen PR. Please take a look.
https://github.com/Immediate-Mode-UI/Nuklear/pull/722
I think more documentation on how to use the layout systems would be nice too :)
Now the move to Doxygen is done on master, maybe it would be good to centralize doc in the source tree? (source files + additional markdown if needed), and then the wiki could be removed, making github.io doc the only source of truth?
i am working on another PR for doxygen. This next one will be HUGE as it adds proper header blocks to all functions. I also have started migrating things to Markdown and am considering pushing those files into the docs directory. Once the PR is up. I would love extra feedback.
I did a little digging about consolidating the documentation. We can absolutely consolidate. However, HEADER.md and Readme.md have very similar information, so we need to pick one.
Readme.md is the only file (to my knowledge) that github will display as a default project page. So i believe that we should migrate all of the HEADER.md content into Readme.md then update the build script to pack in Readme.md instead of header.
Thoughts? Note: this would mean that our github project page information will end up prefixed to the header file. is that okay? Also means that project file would be identical to the main page of the documentation wiki... is that okay? do we want the main wiki page to also be the project page? or do we want different content?
once PR #737 gets merged in. I will start my PR that includes the big changes to the src. There should be (ideally) no code changes; only header blocks added everywhere. I expect every single PR currently out there to end up with merge conflicts once that PR gets merged in. so we might want to figure out some way of handling that. I would be willing to help filter through existing PRs to try to fix the issues, but i don't have write access to those PRs, so it would be me make more PRs to other PRs and hoping the original authors didn't abandon anything.
i don't know if there is a good way of handling this situation other than just brute forcing it.
on a related note. does anyone here know of an easy way for me to find a PR in this project, and get that PR over to my personal fork? There are going to be situations where I would want to help fix a conflict in some one elses PR, but since that PR is setup for This project and not mine, I have to do some weird funny business where I try to branch or clone or add remotes to others forks and checkout and initiate merges on my own; then figure out how to PR back to them. idk it is kind of a mess and I am hoping someone here might know of a cleaner solution. Any advise would be appreciated.
i am working on another PR for doxygen. This next one will be HUGE as it adds proper header blocks to all functions. I also have started migrating things to Markdown and am considering pushing those files into the
docsdirectory. Once the PR is up. I would love extra feedback.
I'm going to open my C++ nuklear wrapper library soon. It also uses Doxygen, so I will try to build both together and see if there is anything specific I need for Doxygen settings.
I'm going to open my C++ nuklear wrapper library soon.
Hello @Xeverous , is there an ETA on when do you plan to release your library?
Generally, it is ready. I wanted a bit more polish (like a pure C++ example) but it can be done later. Just need to verify it works after recent merges in Nuklear.
Regarding Doxygen, currently I run it for my code only (which means some repetitions in my documentation) but it would be very nice if I could reference Nuklear source too.
To some extent, the repetitions are unavoidable as the C++ layer sometimes changes the API somewhat (e.g. I replaced begin/end calls with constructor/destructor) and Doxygen itself is very poor when it comes to deduplicating text in documentation (e.g. you can't @copydoc and override description of a parameter).
I will comment here when the repo becomes public.
oh shoot. i have totally forgotten about my PR over the holidays. I will try to prioritize this.
Repo is public: https://github.com/Xeverous/nukleus
- There is no readme, no license and no demo application yet but the project can be built as a static library (to at least verify that the C++ header is compatible with Nuklear's C header). CMake recipe supplied. Requires C++11 or newer.
- The code is documented (with some TODOs - lots of text was copied from Nuklear). You just need to build the documentation with Doxygen. Doxyfile supplied. The most comprehensive pages are "Topics", "Core", "Window" and "Context".
- My library follows and should work with any combination of Nuklear's defines. The C++ API will be selectively enabled, just like Nuklear.
My biggest concern is the compatibility of Doxygen settings. I don't plan to use Nuklear's Doxyfile (if any) but I have some settings (disabled subgrouping, disabled sorting, warning on undocumented param) that may create issues if Nuklear's documentation would be written for a different set of settings.
FYI (about my project's Doxyfile - doxygen -x Doxyfile):
# Difference with default Doxyfile 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca)
PROJECT_NAME = Nukleus
OUTPUT_DIRECTORY = doc
BUILTIN_STL_SUPPORT = YES
SUBGROUPING = NO
EXTRACT_ALL = YES
SORT_MEMBER_DOCS = NO
WARN_NO_PARAMDOC = YES
INPUT = nukleus.hpp
# don't remember what happened here
# most likely .hpp wasn't on the list
FILE_PATTERNS = [...] (long list)
RECURSIVE = YES
INLINE_SOURCES = YES
HTML_DYNAMIC_SECTIONS = YES
DISABLE_INDEX = YES
GENERATE_TREEVIEW = YES
FULL_SIDEBAR = YES
GENERATE_LATEX = NO
PREDEFINED = NK_INCLUDE_COMMAND_USERDATA \
NK_INCLUDE_DEFAULT_ALLOCATOR \
NK_INCLUDE_DEFAULT_FONT \
NK_INCLUDE_FIXED_TYPES \
NK_INCLUDE_FONT_BAKING \
NK_INCLUDE_STANDARD_BOOL \
NK_INCLUDE_STANDARD_IO \
NK_INCLUDE_STANDARD_VARARGS \
NK_INCLUDE_VERTEX_BUFFER_OUTPUT
CLASS_GRAPH = GRAPH
I have added tons of code to my Nuklear C++ API wrapper library and changed my previous decision. Instead of pulling Nuklear's Doxygen code, I write my own based on Nuklear's doc-comments because:
- Nuklear at the moment seems to have very low/slow maintenance and I don't want to wait.
- The C++ API is very similar, usually just shifts stuff around (e.g.
nk_button_label(ctx, "text")=>win.button_label("text")) so it's better if it's documented similar way instead of redirecting to underlying's library documentation (such linking would be very tedious) - Sometimes the C++ API changes things for language reasons (availability of templates, references etc.) and need to refactor Nuklear's doc-comments
- Doxygen lacks advanced documentation manipulation features. Even
@copydocis pretty limited and can not be used to override similar function parameter descriptions.
Any news from others? I'm still interested in the issue because I'm still learning some parts of the API and have plenty of undocumented code.
I haven't looked at Nuklear in a bit, however I do have more free time now, maybe, just maybe I'll actually get to work. Otherwise, glad to to see you're still at it @Xeverous
I don't know where the documentation left off. I think PR #737 is still open and I was waiting on that before I started the PR with the huge changes to header blocks.
Since it's been a year, my changes are probably wildly out of date. And I don't know if I have a time to update it. This thread certainly seems dead.
Currently Nuklear's maintenance seems dead. Just because a lot of time passed doesn't meant it got outdated (very few commits were made since). I don't think there will be a large merge problem - the bigger problem IMO right now is lack of maintainers.
yeah. There are tons of PRs up. and i think that, if the current maintainers are struggling to keep up (no issue there, we are all busy). then either delegation would be in order, or relaxing the requirements to get merged. I can understand wanting some enforcement for certain additions. like some percentage of demos working correctly; but i was running into an issue where the checkbox and radio button improvement still has not been merged because there is an issue in 1 demo where the bounding box is 1 pixel too short, and that has kept that PR from merging for 3 years.
I understand that people have a different level of acceptability than me; but at some point, if you want a crowdsourced project, you need to let the crowd actually contribute.
i considered forking this and working on the merging in all of the existing PRs.... except that I don't know of a good way to do that, because it seems like github/git doesn't have a great way to find the PRs for the upstream and apply them to a down stream without explicitly going to each PR, finding the fork URL, and setting up some kind of connection and new PR yourself..... which is fine for 1 or 2, but not 77
i want to be clear. I love this project and everyone who has worked on it. I am very happy that it exists and nothing that I have said should be taken as an insult to the maintainers in any way. we are all human and all have busy lives and competing priorities.
I don't know of a good way to do that, because it seems like github/git doesn't have a great way to find the PRs for the upstream and apply them to a down stream
I don't think there is. But I think that if current maintainers can not even reply to PRs or issues in months (last merge to master was 6 months ago) I think forking the project is the only way.
can this project just be "opened up" to anyone who wants to contribute? i don't know how github security works.
Only the repository owner (or maintainers) can manage issues (e.g. close issues from anyone) and merge/reject PRs. You would need to ask them for higher permissions.
i considered forking this and working on the merging in all of the existing PRs
Any particular PRs you would like to see merged? There are a few approved that could likely go. More reviews are always appreciated.