Skip to content

Migrate to mkdocs #3143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Migrate to mkdocs #3143

wants to merge 5 commits into from

Conversation

vemonet
Copy link

@vemonet vemonet commented May 28, 2025

Summary of changes

Hi @nicholascar @ajnelson-nist, as discussed in #3128 I migrated the documentation from rst format with sphinx, to markdown with mkdocs (material for mkdocs)

  • Migrated all .rst pages to .md. I merged the 5 plugins pages in 1 (all pages were small ~50 lines, it's easier to maintain and read to have them all in one page, without being overwhelming), we can also put it back as 5 different pages if required.

  • Migrated all docstrings to markdown with google style, generated API references docs using mkdocstring e.g.

    def _make_redirect_request(request: Request, http_error: HTTPError) -> Request:
        """Create a new request object for a redirected request.
    
        The logic is based on [HTTPRedirectHandler](https://github.com/python/cpython/blob/b58bc8c2a9a316891a5ea1a0487aebfc86c2793a/Lib/urllib/request.py#L641-L751) from urllib.request.
        
        Example:
            ```python
            >>> req = _make_redirect_request(request, http_error)
    
            ```
    
        Args:
            request: The original request that resulted in the redirect.
            http_error: The response to the original request.
    
        Returns:
            A new request object to the location indicated by the response.
    
        Raises:
            HTTPError: the supplied `http_error` if the redirect request cannot be created.
            ValueError: If the response code is None.
        """
  • All doctests are working and passing, they just required to add an extra newline before the ending ```

  • I have previously mentioned I was planning to look into alternatives for running markdown codeblocks, e.g. usingpytest-markdown-docs. Introducing tests on the markdown codeblocks would require a lot of changes to the documentation, there are already enough.

  • I chose indigo for the primary color because it is one of the few colors that constrats well with the green and yellow of the logo, and it is close to the background of the original semantic web logo

  • Website splits in 3 top nav: Usage, API Reference, Development. With the pages in the current section listed on the left

  • Updated the .readthedocs.yaml config according to their docs, removed sphinx from dependencies and updated most build scripts

You can easily start it locally with:

poetry install
poetry run mkdocs serve

I have included screenshots of the website, let me know if there is anything that needs to be done

Screenshot 2025-05-28 at 12 17 16 Screenshot 2025-05-28 at 12 21 50 Screenshot 2025-05-28 at 15 33 07

Checklist

  • Checked that there aren't other open pull requests for
    the same change.
  • Checked that all tests and type checking passes.
  • If the change adds new features or changes the RDFLib public API:
    • Created an issue to discuss the change and get in-principle agreement.
    • Considered adding an example in ./examples.
  • If the change has a potential impact on users of this project:
    • Added or updated tests that fail without the change.
    • Updated relevant documentation to avoid inaccuracies.
    • Considered adding additional documentation.
  • Considered granting push permissions to the PR branch,
    so maintainers can fix minor issues and keep your PR up to date.

vemonet added 5 commits May 28, 2025 13:27
…r mkdocs. Add mkdocs.yml with proper configuration, enable automated generation of the doc API from the docstring, and start converting a few pages (index, getting started, developers) for demo.
… docs using pytest-markdown-docs. Needed to comment 1 small test that seemingly should fail (AttributeError: DefinedNamespace like object has no attribute '_NS', indeed the DefinedNamespace class expect a _NS, so it makes sense it fails) but for some reason it was not properly failing when ran with regular pytest, but it fails with pytest-markdown-docs
…to markdown with google style, updated config for mkdocs (readthedocs, tox, task)

fixed RDFLib#3128
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant