Is it possible to get the "Clipboard - Gramps" entities list?

Development
1

I would like to get the “Clipboard - Gramps” entities list from Gramps code (EditPerson class). Is it possible to implement this? Thanks

2

The ClipboardWindow class has an attribute otree which is a ClipboardListModel. This stores the list of objects held in the clipboard.

2 Likes
3

The Sphinx docs does not find this information.

How can information be be added to the Sphinx docs?

4

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.

1 Like
5

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

  1. 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

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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

6

The Sphinx reStructuredText Primer is a good reference.

1 Like
7

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.