René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"The API Reference documents too few modules","articleBody":"The [API Reference](https://gitpython.readthedocs.io/en/latest/reference.html) in the Sphinx documentation is missing some modules. But I am unsure exactly which ones should be added. There seem to be three cases.\r\n\r\nAt least one omission should be corrected:\r\n\r\n1. The top-level `git` module is not listed, and while its `__version__` attribute is listed explicitly, `git.refresh` is not, so the `Git.refresh` method that should only be called directly in rare, unusual cases has its documentation included in the reference page, while the `git.refresh` function that is much more reasonable to call is omitted.\r\n\r\nBut for some of the other modules that aren't listed there, it seems intentional. These appear to divide into two more cases:\r\n\r\n2. Modules that are packages where everything interesting is defined in submodules.\r\n\r\n4. Modules where it may make sense to avoid creating the appearance that users of GitPython should ever directly use anything from them.\r\n\r\nThese are all the modules of GitPython that are not listed in `doc/source/reference.rst`, such that they do not have their public symbols automatically collected, and presented with docstrings, by Sphinx autodoc:\r\n\r\n```text\r\ngit\r\ngit.compat\r\ngit.db\r\ngit.index\r\ngit.objects\r\ngit.objects.submodule\r\ngit.refs\r\ngit.repo\r\ngit.types\r\n```\r\n\r\nCase 1, which should be included at least to get `git.refresh` and its docstring, is of course:\r\n\r\n```text\r\ngit\r\n```\r\n\r\nCase 2, where maybe they shouldn't be included because nothing of interest is directly contained in them, are:\r\n\r\n```text\r\ngit.index\r\ngit.objects\r\ngit.objects.submodule\r\ngit.refs\r\ngit.repo\r\n```\r\n\r\nCase 3, where maybe they shouldn't be included, or shouldn't be included without making clear in their module docstrings that they should not usually be used, are:\r\n\r\n```text\r\ngit.compat\r\ngit.db\r\ngit.types\r\n```\r\n\r\nRegarding this third case, symbols in these modules are referenced in docstrings or type annotations. More of these references are references from a technical Sphinx perspective than before, as of #1850, but it was always necessary to be able to understand what was in them, to understand what some names referred to and their significance.\r\n\r\nTherefore, for this third case, even if I am correct in my belief that they were omitted to discourage direct use, it seems to me that it may be best include them, with suitable guidance added in module docstrings (which autodoc will ensure is rendered at the top of the relevant section).\r\n\r\nI am unsure what should be done here, and unsure if all three of those modules of the third kind are really in the same situation. But even if they are and the approach I suggest is to be taken, I am unsure how strongly their use should be discouraged, and if a reason should be given (and if so, what reasons). This is what I know about them, that is related to this:\r\n\r\n- `git.compat` is to some extent a relic of when Python 2 was supported, and besides that it is mostly used within GitPython to deal with encoding, yet it may no longer be needed if/when GitPython's handling of strings and bytes is improved in the future, and it may not be useful for use in codebases that handle such things correctly from the start.\r\n- `git.db` is related to the gitdb library, and one of the symbols is includes in `__all__` is `GitDB`, whose use is today discouraged. The other symbol is `GitCmdObjectDB`. That might be seen today as a workaround for the way GitPython expects to receive an injected object database dependency with a `GitDB`-like interface. However, `GitCmdObjectDB` appears in various places and it's useful to understand it to understand the significance of it being the default. It seems to me that the `git.db` module should not only be included in documentation, but that no special effort should be made to discourage its use (though the `GitDB` could be clarified as not recommended).\r\n- `git.types` provides types used throughout GitPython, and the `assume_never` function. The types do not have docstrings. However, it may still be useful to list them so references in Sphinx documentation to them are rendered as links and so it is clear they really are part of GitPython rather than external. In addition, some of the types are `TypedDict`s, and I *think* autodoc will list the members. (If what ought to be done hinges on that, then I can to an experiment first to check; you can let me know.)\r\n\r\nMy sense is that `git.db` and `git.types` should be promoted to have the same status as most modules; while `git.compat` should either be similarly promoted, or a discouragement to use it added to its docstring, or both.\r\n\r\nThese are all part of GitPython's public interface: they are named as conventionally public names, and while the documentation currently omits pages for them, it nowhere characterizes them as private or states that they should not be used in code outside GitPython. So to avoid breaking backward compatibility, they should remain public.\r\n\r\nBut public use of them (use outside GitPython) could be *deprecated* if appropriate. As far as I can tell, that should either be done in `git.compat` only, or nowhere. If it is to be done for `git.compat`, then it could be accompanied by renaming it to `git._compat` and having uses in GitPython use that name, while `git.compat` would re-export its public names (and could also emit `DeprecationWarning`).","author":{"url":"https://github.com/EliahKagan","@type":"Person","name":"EliahKagan"},"datePublished":"2024-03-02T01:39:03.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":2},"url":"https://github.com/1854/GitPython/issues/1854"}