diff --git a/docs/python/documentation.rst b/docs/python/documentation.rst index 29c15bd..12193a3 100644 --- a/docs/python/documentation.rst +++ b/docs/python/documentation.rst @@ -102,8 +102,11 @@ Review the broken links in the ``_linkcheck/output.txt`` file: .. _readthedocs: -Create a ReadTheDocs project ----------------------------- +ReadTheDocs +----------- + +Create a project +~~~~~~~~~~~~~~~~ #. Sign in to `ReadTheDocs `__ #. Click *Import a Project* @@ -133,8 +136,8 @@ Create a ReadTheDocs project #. Uncheck *Active* #. Click *Save* -Configure the ReadTheDocs project ---------------------------------- +Configure the project +~~~~~~~~~~~~~~~~~~~~~ .. tab-set:: @@ -160,8 +163,8 @@ Configure the ReadTheDocs project At present, Python 3.9 is used, because ReadTheDocs is not compatible with Python 3.10. -Redirect a ReadTheDocs project ------------------------------- +Redirect a project +~~~~~~~~~~~~~~~~~~ #. Replace ``docs/_templates/layout.html`` with the below, replacing ``SUBDOMAIN``: diff --git a/docs/python/i18n.rst b/docs/python/i18n.rst index 8731f30..8df6ad2 100644 --- a/docs/python/i18n.rst +++ b/docs/python/i18n.rst @@ -37,7 +37,7 @@ See `Adding resources in bulk /LC_MESSAGES/django.po' @@ -46,54 +46,46 @@ Translate with Transifex Whenever text in the interface is added or updated, you must extract the strings to translate from the code files into PO files by running: -.. grid:: 2 +.. code-block:: bash + :caption: Django - .. grid-item-card:: Django + django-admin makemessages -l en_US --no-obsolete - .. code:: bash +.. code-block:: bash + :caption: Python (example) - django-admin makemessages -l en_US --no-obsolete - - .. grid-item-card:: Python (example) - - .. code:: bash - - pybabel extract -F babel.cfg -o messages.pot . - pybabel update -i messages.pot -d locale + pybabel extract -F babel.cfg -o messages.pot . + pybabel update -i messages.pot -d locale Then, push the PO files to Transifex with: -.. code:: bash +.. code-block:: bash tx push -s If you made local changes to translations, push the translations to Transifex. For example: -.. code:: bash +.. code-block:: bash tx push -t -l en When ready, pull the translations from Transifex with: -.. code:: bash +.. code-block:: bash tx pull -f -a Then, compile the PO files to MO files with: -.. grid:: 2 - - .. grid-item-card:: Django - - .. code:: bash - - python manage.py compilemessages +.. code-block:: bash + :caption: Django - .. grid-item-card:: Python (example) + python manage.py compilemessages - .. code:: bash +.. code-block:: bash + :caption: Python (example) - pybabel compile -f -d locale + pybabel compile -f -d locale Reference: Django `Translation `__ diff --git a/docs/python/style_guide.rst b/docs/python/style_guide.rst index 8d0f306..ef2fe23 100644 --- a/docs/python/style_guide.rst +++ b/docs/python/style_guide.rst @@ -76,7 +76,7 @@ Warnings The `warnings.catch_warnings(record=True) `__ context manager catches instances of ``warnings.WarningMessage``, not instances of the original warning classes. To reissue a warning, you need to do, like in `Apache Airflow `__: - .. code:: python + .. code-block:: python warnings.warn_explicit(w.message, w.category, w.filename, w.lineno, source=w.source) @@ -84,7 +84,7 @@ Warnings Because the additional required arguments are unavailable, you can't do: - .. code:: python + .. code-block:: python warnings.warn(category(w.message, var1, var2)) # var1 and var2 are indeterminable diff --git a/docs/rust/index.rst b/docs/rust/index.rst index 94e3b6e..07fc92b 100644 --- a/docs/rust/index.rst +++ b/docs/rust/index.rst @@ -30,6 +30,13 @@ Preferences .. Candidates for preferences https://github.com/open-contracting/cardinal-rs/issues/4 +Performance +----------- + +.. seealso:: + + `coz `__ profiler + Code style ---------- @@ -151,14 +158,14 @@ If you're getting confusing compile errors, especially any involving type annota - Your annotations are correct. If you change your code but don't change your annotations, the compiler might report errors that are distantly related to the misannotation. - You duck type using trait objects: for example, ``Box`` to use ``std::io:stdin()`` and ``File::open(file).unwrap()`` interchangeably. The compiler can't determine which traits are relevant across the two types. -If errors relate to ownership, try: +If errors relate to ownership, try using: -- Using ``Arc>``, as discussed in sections `16.3 `__ and `20.2 `__ of *The Rust Programming Language*. -- Using ``Option`` with ``take()``, as discussed in sections `17.3 `__ and `20.3 `__ of *The Rust Programming Language*. +- ``Arc>``, as discussed in sections `16.3 `__ and `20.2 `__ of *The Rust Programming Language*. +- ``Option`` with ``take()``, as discussed in sections `17.3 `__ and `20.3 `__ of *The Rust Programming Language*. -To reduce the number of allocations, try: +To reduce the number of allocations, try using: -- Using ``mem::take`` or ``mem::replace`` (`Rust Design Patterns `__). +- ``mem::take`` or ``mem::replace`` (`Rust Design Patterns `__). .. seealso::