On the other hand, based on our history (see also my answer to I believe nobody will ever properly maintain Tribler documentation anyway and I have come to believe that all of our documentation should solely be automatically generated. For example, Tribler's automatic class documentation has been broken for. That said, on the one hand there is a case to be made that Tribler will never need the above functionality. md files, all changes to the source code would require the documentation to be rebuilt using custom tooling and to be pushed to the repository. I'd consider this pretty much impossible to do without tooling (otherwise, you would have to mirror all functions and their docstrings in the documentation with manual standardized formatting). Automatic class documentation (e.g., ).You could also opt to link to the external files instead of explicitly including them in the documentation, but this may make the documentation harder to read. md using a custom tool and making them runnable, this is just much harder. You could also do this by extracting code snippets from the. Separating code snippets into stand-alone files makes it easier to run them for automatic testing. Creating this by hand is annoying, but not impossible. Some concrete examples that are actually used in IPv8: However, it is important to know what you're "losing out"* on. If you accept the required sacrifices to gain GitHub rendering and prefer working in MD, this becomes a matter of taste/personal preference and I have no further comment on this. Perhaps we should do something radical and drop all documentation that is not a docstring or installation instructions? Requiring everyone to write docstrings seems like something we can realistically Fair enough. Tribler also evolves way too fast to keep stable documentation without tremendous effort (no matter what format we use). Nobody ever gives any love to the documentation. #4656 has been open since 2019 for exactly this.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |