How can "Useful Snippets" be proposed for the Sphinx developer docs

Development
1

The Sphinx-powered Gramps-project docs are an important developer resource. (See the pinned thread in the Manuals section of this Discourse forum.)

But the footer has no link to a page in the wiki that explains how to become a contributor volunteer to that CMS or to contribute an addition. (Will add as a link to Header for Category:Developers/Reference )

Can we add such a footer link? And how is content contributed to the Spinx system?

2

Perplexity.ai prompt and response:

What is the workflow to add another “useful snippets” to a Sphinx documentation site for a user who has never used Sphinx and has no account. (Include how to identify the maintainer and contact info of the Sphinx generated website.)

To add “useful snippets” to a Sphinx documentation site as a new user, follow these steps:

  1. Identify the maintainer: Look for a “Contact” or “About” page on the Sphinx-generated website. This information is often found in the footer or navigation menu[1].

  2. Contact the maintainer: If contact information is available, reach out to the maintainer via email or through the provided contact form. Explain that you’d like to contribute a useful snippet to the documentation[1].

  3. Propose your snippet: Clearly describe the snippet you want to add and explain its usefulness to the project’s documentation[1].

  4. Follow the maintainer’s instructions: The maintainer will likely provide guidance on how to contribute. This may involve:

    • Creating a GitHub account if the project is hosted on GitHub
    • Forking the repository
    • Making changes in a new branch
    • Submitting a pull request

  5. Format your snippet: Use appropriate Sphinx markup for your contribution. For code examples, use the .. code-block:: directive followed by the language and the code itself[4].

  6. Add doctests if applicable: If your snippet includes Python code, consider adding doctests to ensure the code remains up-to-date and functional[4].

  7. Submit your contribution: Follow the maintainer’s preferred method for submitting changes, whether it’s through a pull request or another means[1].

Remember, as a new contributor, it’s important to respect the project’s guidelines and be patient with the review process. The maintainer may request changes or provide feedback before accepting your contribution.

Citations:
[1] sphinx.ext.doctest – Test snippets in the documentation — Sphinx documentation
[2] Extensions — Sphinx documentation
[3] python - How do I insert highlight or code-block into Sphinx-style docstrings? - Stack Overflow
[4] Describing code in Sphinx — Sphinx documentation
[5] Directives — Sphinx documentation

3

Yes. Please submit a pull request.

4

To submit a PR, don’t I need to know where the Sphinx files are in the Gramps-project GitHub Repository and commit a change to the file?

I searched and cannot find the pertinent files.

Perplexity says the Sphinx installation references a footer.html in a templates and a templates_path = ["_templates"] enabled in the conf.py file. And searching the repository finds multiple instances of a conf.py file and they all have that line. But no footer.html file is found.

I’m following the suggestions after the Perplexity prompt:

In a GitHub repository for a Sphinx-generated documentation project, where is the file to modify the footer? Provide step-by-step instructions on how to add a hotlink in the footer for ‘Contributing guidelines’ that links to http://myExample.org/page. Include the necessary file paths, code snippets, and any configuration changes required in conf.py. Explain how these changes should be committed and pushed to the repository to take effect in the hosted documentation.

Or should I raise an issue? (There’s a “[Sphinx]” MantisBT issue 13152 from January. [resolved Jul 2024] It is a simple linkrot with a suggested replacement waybackmachine URL. So MantisBT doesn’t seem to be an effective channel. This bug is misidentified. The linkrot in the Sphinx page traces back to linkrot in a comment of the AuthorParser – line 198 of gramps/gui/aboutdialog.py. But wouldn’t the Sphinx page still need to be regenerated?)

5

You will have to write it yourself.

There is a stack overflow question titled How can I add a custom footer to Sphinx documentation? which should help.

Create a file called docs/_templates/layout.html containing something like:

{% extends '!layout.html' %}
{% block footer %}
        {{ super() }}
        <!-- your html code here -->
{% endblock %}
1 Like
6

To which docs branch?

Existing footer

image

    <div class="footer" role="contentinfo">
        &#169; Copyright 2001-2019, The Gramps Project.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.0.1.
    </div>
7

Enhancements should be submitted to the master branch.

1 Like
8
9

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.