Modifying the development guide

The following are guidelines and tips for modifying this guide.

Extra reStructuredText roles

Aside, the roles provided out-of-the box, some 3rd-party and custom roles may also be used.

Referencing issues, commits, users, etc

All roles provided by the sphinx-issues extension may be used as described on its page but note that the repository-related and user roles are restricted to the gitlab.gnome.org GitLab instance e.g:

and the default repository for the repository-related roles is GNOME/librsvg e.g:

  • :issue:`1` -> #1,

  • :commit:`550ba0c83939dfd0e829528dc8175639ad92dd83` -> @550ba0c.

Referencing the source tree

:source:

References entries in the librsvg source tree.

The target should be a valid path to an entry in the source tree relative to the source tree root, which may be prepended with a branch name, tag name or commit hash to reference the source tree at that branch, tag or commit.

In other words, the target is of the form [<ref>:][<path>]. <ref>: may be omitted to reference the default branch (main) and <path> may be omitted to reference the source tree root.

For example:

To add to or modify these roles see devel-docs/_extensions/source.py.

Referencing the internals documentation

The following reference entities in the library’s internals documentation:

:internals:crate:

This references a crate.

The target should be the name of the crate e.g :internals:crate:`librsvg_c` -> librsvg_c.

:internals:module:

This references a module.

The target should be a rust-style reference for the module e.g:

  • :internals:module:`rsvg::api` -> api

  • :internals:module:`rsvg::xml::xml2` -> xml2

  • :internals:module:`librsvg_c::handle <librsvg_c::handle>` -> librsvg_c::handle

:internals:struct:
:internals:enum:
:internals:trait:
:internals:type:
:internals:fn:
:internals:macro:
:internals:constant:
:internals:static:

These reference top-level entities.

The target should be the rust-style fully-qualified reference for an entity e.g:

  • :internals:enum:`rsvg::RenderingError` -> RenderingError

  • :internals:struct:`librsvg_c::handle::RsvgHandle` -> RsvgHandle

  • :internals:fn:`rsvg::drawing_ctx::draw_tree` -> draw_tree()

  • :internals:constant:`rsvg::xml::xml2::XML_SAX2_MAGIC` -> XML_SAX2_MAGIC

:internals:struct-field:
:internals:struct-method:
:internals:enum-variant:
:internals:trait-method:
:internals:trait-tymethod:

These reference members of structs, enums, etc.

The target should be the rust-style fully-qualified reference for a member entity. This normally renders as <parent>::<member> but the reference target may be prepended by a ~ (tilde) to render as just <member>.

For example:

  • :internals:struct-field:`rsvg::Length::unit` -> Length::unit

  • :internals:struct-method:`rsvg::element::Element::new` -> Element::new()

  • :internals:struct-method:`~rsvg::element::Element::new` -> new()

  • :internals:enum-variant:`rsvg::RenderingError::InvalidId` -> RenderingError::InvalidId

Note

internals:trait-method references a provided trait method i.e a trait method that has a default implementation, such as ElementTrait::draw(); while internals:trait-tymethod references a required trait method i.e a trait method that only has a prototype, such as Normalize::normalize().

To reference a struct’s implementation of a trait’s method, use internals:struct-method.

To add to or modify these roles see devel-docs/_extensions/internals.py.

Referencing RUSTSEC advisories

:rustsec:

References the official page of a RUSTSEC advisory.

The target should be the ID of the advisory e.g :rustsec:`2020-0146` -> RUSTSEC-2020-0146.