158 lines
5.6 KiB
ReStructuredText
158 lines
5.6 KiB
ReStructuredText
: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`.
|