I would like to get the “Clipboard - Gramps” entities list from Gramps code (EditPerson class). Is it possible to implement this? Thanks
The ClipboardWindow class has an attribute otree
which is a ClipboardListModel. This stores the list of objects held in the clipboard.
The Sphinx docs does not find this information.
How can information be be added to the Sphinx docs?
In this case, you would need to make sure that the classes are correctly annotated in their docstrings. Then add a section to the docs/coregui/gui.rst file.
Asked Perplexity to collate (with citations) the wiki docs about modifying Gramps source for Sphinx
To effectively document Python source code for inclusion in the Gramps developer documentation managed by Sphinx, developers should adhere to specific guidelines and practices. Here’s a summarized overview based on the relevant sources:
Key Guidelines for Documenting Python Source Code in Gramps
-
Docstrings:
- Use docstrings to document all classes, functions, and methods. These should be formatted according to reStructuredText (reST), which is compatible with Sphinx for automatic documentation generation. Each docstring should include:
- A brief description of the function or class.
- Parameters and their types.
- Return types.
- Any exceptions raised.
- Example format:
def example_function(param1: str) -> bool: """ Brief description of the function. :param param1: Description of the parameter. :return: Description of the return value. """ pass
- Use docstrings to document all classes, functions, and methods. These should be formatted according to reStructuredText (reST), which is compatible with Sphinx for automatic documentation generation. Each docstring should include:
-
Sphinx Configuration:
- Ensure that the
conf.py
file in the Sphinx documentation directory is properly set up to include the paths to your modules. This allows Sphinx to find and document your code effectively.
- Ensure that the
-
Editing API Generating Files:
- In addition to writing docstrings, developers must also edit the API generating reST files located in the
docs
directory. This step is crucial for ensuring that Sphinx can extract and display the documentation correctly.
- In addition to writing docstrings, developers must also edit the API generating reST files located in the
-
Coding Standards:
- Follow PEP 8 coding standards for consistency in naming conventions, indentation, and overall code structure. This includes using clear and descriptive names for functions and variables.
-
Class Headers:
- Each class should have a simple header comment that helps identify it within the file, especially when multiple classes exist in a single file.
-
Best Practices:
- Document all core classes thoroughly, while non-core classes should still be documented but may not require as extensive detail.
- Regularly run linting tools (like
pylint
) on your code to ensure that documentation is up-to-date and adheres to style guidelines.
-
Contribution Guidelines:
- Familiarize yourself with Gramps’ contribution guidelines, which provide additional context on how to write effective documentation that benefits both users and developers.
Sources
By following these guidelines, developers can ensure that their contributions are well-documented and easily integrated into the Gramps project’s Sphinx-managed documentation.
Citations:
[1] pydoc — Documentation generator and online help system — documentación de Python - 3.13.0
[2] Documenting Python Code: A Complete Guide – Real Python
[3] Documenting Python Code and Projects | TestDriven.io
[4] Programming guidelines - Gramps
[5] https://www.datacamp.com/tutorial/documenting-python-code
[6] Documentation in Python: Methods and Best Practices - Swimm
[7] Documentation — The Hitchhiker's Guide to Python
[8] python - Documenting and detailing a single script based on the comments inside - Stack Overflow
[1] Using database API - Gramps
[2] Getting started with Gramps development - Gramps
[3] Documentation - Gramps
[4] isotammi-addons/source/SuperTool/README.md at master · Taapeli/isotammi-addons · GitHub
[6] Addon:Isotammi addons - Gramps
[7] GitHub - gramps-project/gramps-web-api: A RESTful web API for Gramps - backend of Gramps Web
[8] Using Supertool to import Attributes and URLs - An example
The Sphinx reStructuredText Primer is a good reference.
Do you think that it is a viable idea to use SuperTool scripts to populate the Useful Snippets in the Sphinx API docs?
@kku has been wanting a way to organize the example scripts. And SuperTools scripts would give fully functional stand-alone sample code. (Although we would have to complete the docs on evolving a proof-of-concept in SuperTool and wrapping a GUI around it as an addon… Gramplet, Tool, Report, Quick Report.)
I was thinking that a good way to answer the “polling the Clipboard” inquiry from @Urchello would be with a SuperTool script in the Dashboard.
This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.