librsvg source for verification 2026-05-22
This commit is contained in:
157
devel-docs/devel_docs_mod_guide.rst
Normal file
157
devel-docs/devel_docs_mod_guide.rst
Normal file
@@ -0,0 +1,157 @@
|
||||
:orphan:
|
||||
|
||||
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
|
||||
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_,
|
||||
some 3rd-party and custom roles may also be used.
|
||||
|
||||
Referencing issues, commits, users, etc
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
All roles provided by the `sphinx-issues
|
||||
<https://github.com/sloria/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:
|
||||
|
||||
- ``:user:`federico``` -> :user:`federico`,
|
||||
- ``:issue:`GNOME/gnome-shell#5415``` -> :issue:`GNOME/gnome-shell#5415`,
|
||||
|
||||
and the default repository for the repository-related roles is
|
||||
`GNOME/librsvg <https://gitlab.gnome.org/GNOME/librsvg>`_ e.g:
|
||||
|
||||
- ``:issue:`1``` -> :issue:`1`,
|
||||
- ``:commit:`550ba0c83939dfd0e829528dc8175639ad92dd83```
|
||||
-> :commit:`550ba0c83939dfd0e829528dc8175639ad92dd83`.
|
||||
|
||||
Referencing the source tree
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. rst:role:: 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:
|
||||
|
||||
- ``:source:`rsvg/src/``` -> :source:`rsvg/src/`
|
||||
- ``:source:`Maintainers <README.md#maintainers>```
|
||||
-> :source:`Maintainers <README.md#maintainers>`
|
||||
- ``:source:`550ba0c83939dfd0e829528dc8175639ad92dd83:rsvg/src/```
|
||||
-> :source:`550ba0c83939dfd0e829528dc8175639ad92dd83:rsvg/src/`
|
||||
- ``:source:`2.59's README <2.59.0:README.md>```
|
||||
-> :source:`2.59's README <2.59.0:README.md>`
|
||||
- ``:source:`2.59.1:``` -> :source:`2.59.1:`
|
||||
|
||||
To add to or modify these roles see
|
||||
:source:`devel-docs/_extensions/source.py`.
|
||||
|
||||
Referencing the internals documentation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The following reference entities in the library's internals documentation:
|
||||
|
||||
.. rst:role:: internals:crate
|
||||
|
||||
This references a crate.
|
||||
|
||||
The target should be the name of the crate e.g
|
||||
``:internals:crate:`librsvg_c``` -> :internals:crate:`librsvg_c`.
|
||||
|
||||
.. rst:role:: internals:module
|
||||
|
||||
This references a module.
|
||||
|
||||
The target should be a rust-style reference for the module e.g:
|
||||
|
||||
- ``:internals:module:`rsvg::api``` -> :internals:module:`rsvg::api`
|
||||
- ``:internals:module:`rsvg::xml::xml2```
|
||||
-> :internals:module:`rsvg::xml::xml2`
|
||||
- ``:internals:module:`librsvg_c::handle <librsvg_c::handle>```
|
||||
-> :internals:module:`librsvg_c::handle <librsvg_c::handle>`
|
||||
|
||||
.. rst:role:: internals:struct
|
||||
.. rst:role:: internals:enum
|
||||
.. rst:role:: internals:trait
|
||||
.. rst:role:: internals:type
|
||||
.. rst:role:: internals:fn
|
||||
.. rst:role:: internals:macro
|
||||
.. rst:role:: internals:constant
|
||||
.. rst:role:: 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```
|
||||
-> :internals:enum:`rsvg::RenderingError`
|
||||
- ``:internals:struct:`librsvg_c::handle::RsvgHandle```
|
||||
-> :internals:struct:`librsvg_c::handle::RsvgHandle`
|
||||
- ``:internals:fn:`rsvg::drawing_ctx::draw_tree```
|
||||
-> :internals:fn:`rsvg::drawing_ctx::draw_tree`
|
||||
- ``:internals:constant:`rsvg::xml::xml2::XML_SAX2_MAGIC```
|
||||
-> :internals:constant:`rsvg::xml::xml2::XML_SAX2_MAGIC`
|
||||
|
||||
.. rst:role:: internals:struct-field
|
||||
.. rst:role:: internals:struct-method
|
||||
.. rst:role:: internals:enum-variant
|
||||
.. rst:role:: internals:trait-method
|
||||
.. rst:role:: 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```
|
||||
-> :internals:struct-field:`rsvg::Length::unit`
|
||||
- ``:internals:struct-method:`rsvg::element::Element::new```
|
||||
-> :internals:struct-method:`rsvg::element::Element::new`
|
||||
- ``:internals:struct-method:`~rsvg::element::Element::new```
|
||||
-> :internals:struct-method:`~rsvg::element::Element::new`
|
||||
- ``:internals:enum-variant:`rsvg::RenderingError::InvalidId```
|
||||
-> :internals:enum-variant:`rsvg::RenderingError::InvalidId`
|
||||
|
||||
.. note::
|
||||
|
||||
:rst:role:`internals:trait-method` references a **provided** trait
|
||||
method i.e a trait method that has a default implementation, such as
|
||||
:internals:trait-method:`rsvg::element::ElementTrait::draw`;
|
||||
while :rst:role:`internals:trait-tymethod` references a **required**
|
||||
trait method i.e a trait method that only has a prototype, such as
|
||||
:internals:trait-tymethod:`rsvg::length::Normalize::normalize`.
|
||||
|
||||
To reference a struct's implementation of a trait's method, use
|
||||
:rst:role:`internals:struct-method`.
|
||||
|
||||
To add to or modify these roles see
|
||||
:source:`devel-docs/_extensions/internals.py`.
|
||||
|
||||
Referencing RUSTSEC advisories
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. rst:role:: 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`.
|
||||
Reference in New Issue
Block a user