Commit Graph

939 Commits

Author SHA1 Message Date
Adam Turner
be52db2bb3
Support placeholders for years in copyright (#12910) 2024-10-04 13:52:29 +01:00
Adam Turner
dfa29f9d4a Add a missing word 2024-10-04 10:56:48 +01:00
Adam Turner
5eb68b2bff Remove list of cross-reference roles 2024-10-03 22:20:55 +01:00
Tim Hoffmann
4080be1e82
Improve cross-reference documentation (#12944)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-10-03 15:58:37 +01:00
Tim Hoffmann
b16e196a60
Improve `autodoc` docs (#12935)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-10-02 23:02:48 +00:00
Adam Turner
702ba34aff
Restructure `autodoc` documentation (#12932) 2024-10-01 14:15:24 +01:00
Adam Turner
45b7ebdc17
Allow using GMT in the HTML last updated format (#12907) 2024-09-22 07:55:09 +01:00
Tim Hoffmann
3b9aa9cace
Format `literalinclude` directive options (#12780)
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
2024-09-18 02:55:14 +01:00
khanxmetu
56716ed514
Clearly specify `latex_engine` defaults (#12876)
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
2024-09-18 01:42:47 +01:00
Wei-Hsiang (Matt) Wang
e35e7b0fbe
Remove unnecessary `:func: and :meth:` parentheses (#12848) 2024-09-01 06:33:28 +01:00
Jean-François B.
9943274033
LaTeX: clarify some docs, add syntax highlighting (refactoring) (#12818) 2024-08-23 18:04:38 +02:00
Tim Hoffmann
49c3b21c60
Format directive options and add some missing ones (#12779)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-08-14 20:59:50 +01:00
Adam Turner
fadb6b10cb
Stop exiting early with `--fail-on-warnings; add --exception-on-warning` (#12743)
Co-authored-by: Jeremy Maitin-Shepard <jbms@google.com>
2024-08-13 17:12:42 +01:00
Jeremy Bowman
0cbdd98ffb
Correctly support custom gettext output templates (#12645)
Co-authored-by: Jeremy Bowman <jmbowman@alum.mit.edu>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-08-11 20:34:04 +01:00
Tim Hoffmann
4cf8f7a093
Restructure documentation for the toctree directive (#12725)
Structure the options using `.. rst:directive:option::` and adapt some descriptions where suitable.

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-08-11 16:36:01 +01:00
Adam Turner
55eddad705 Use proper Pygments lexers 2024-07-24 15:21:25 +01:00
Adam Turner
b88905b6f7 Use long options to sphinx-build in our documentation 2024-07-24 15:21:25 +01:00
Adam Turner
217f267822
Do not overwrite user-supplied data by default when copying (#12647) 2024-07-22 16:00:16 +01:00
Adam Turner
9e3f4521db
Drop support for Python 3.9 (#12633) 2024-07-22 15:05:15 +01:00
Bénédikt Tran
aacca3064e
Remove support for the Sphinx 0.5 `intersphinx_mapping` format (#12083)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-07-22 12:59:59 +01:00
Chris Sewell
dabacdf5f8
Turn `show_warning_types` on by default (#12597)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-07-20 21:07:06 +01:00
James Addison
cc08854bc2
linkcheck: Update configuration defaults for Sphinx 8.0 (#12630)
- Links that respond with HTTP 401 (unauthorized) responses are now considered ``broken`` by default.
- Timeouts that occur when checking a link are now reported with a distinct `timeout` status code, instead of the previous ``broken``.
- The previous behaviours are still available and can be configured on an opt-in basis per-project using ``conf.py``.

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-07-20 20:41:22 +01:00
Adam Turner
18ac58bd53 Fix possibly-invalid HTML when a rubric node is manually created 2024-07-15 10:04:48 +01:00
Adam Turner
3456ff3ca3
Add all admonitions to `directives.rst` (#12572)
Also improve documentation for the *versionchanged* directives.
2024-07-15 02:26:05 +01:00
Adam Turner
0f38c9c15d Emend various spelling errors 2024-07-15 02:16:34 +01:00
Adam Turner
7b570c06a1 Standardise on a common directive for describing code snippets 2024-07-15 02:15:52 +01:00
Adam Turner
1252c7b549 Use "rst" consistently for code and highlighting directives 2024-07-15 02:15:52 +01:00
Adam Turner
f2640a4286 Standardise on "reStructuredText" over "reST" in documentation 2024-07-15 02:15:52 +01:00
Adam Turner
26576590ed Make the domain referencing role targets more specific 2024-07-15 01:59:42 +01:00
Chris Sewell
41b363dbff
[rst] Add level option to rubric directive (#12506)
This commit adds a `level` option to the `rubric` directive, which propagates a `level` attribute to the `rubric` node,
and allows renderers to select a specific heading level.

Logic for this attribute has been added to the HTML5 and LaTeX builder.
2024-07-14 05:52:58 +02:00
Jean-François B
aa6dac81ec
LaTeX: Revamp the styling of all admonitions (#12508)
In LaTeX output, all admonitions now also have a title row with icon.

The ``xcolor`` LaTeX package is now required and the ``fontawesome5`` LaTeX package is needed for the icons.
2024-07-13 17:33:22 +01:00
Adam Turner
3b19a7b4ba Add missing `docutils` warning type in the documentation 2024-07-13 07:16:58 +01:00
Trevor Bekolay
2c0943784c
Disallow module cycles in autosummary (#6792)
Consider the following piece of reST::

  .. automodule:: sphinx.ext.autosummary
     :members:

     .. autosummary::

        sphinx.ext.autosummary.Autosummary

This inserts an autosummary after the module docstring, but before
the members of the module. Without the change in this commit, this
would fail because `import_by_name` would attempt to import::

    sphinx.ext.autosummary.sphinx.ext.autosummary.Autosumary

because the prefix (from the parent) is `sphinx.ext.autosummary`,
and the name is `sphinx.ext.autosummary.Autosummary`, which is able
to be imported from `sphinx.ext.autosummary`, but is not the way
that anyone would want to refer to it.

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
2024-07-13 06:37:50 +01:00
Rafael Fontenelle
9234d0b08d
Add missing backtick to close literal role in configuration.rst (#12547) 2024-07-11 21:29:52 +01:00
Ashley Whetter
e38a60d3f2
Add `py:type` directive and role for documenting type aliases (#11989)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-07-11 12:15:54 +01:00
Stephen Finucane
6b37a6b2a2
Allow explicitly specifying modules in the coverage builder (#11592)
Currently there is no mechanism to identify totally undocumented modules
in the coverage builder, unlike with partially documented modules.
Resolve this by introducing a new ``coverage_modules`` config option.
This is a list of modules that should be documented somewhere
within the documentation tree. 
Any modules that are specified in the configuration value but 
are not documented anywhere will result in a warning. 
Likewise, any modules that are not in the config option but 
are documented somewhere will result in a warning.

Signed-off-by: Stephen Finucane <stephen@that.guru>
2024-07-11 07:36:36 +01:00
Thomas Fanning
6cc1177d10
Allow configuring the separator used in numbering equations (#12523)
Co-authored-by: Thomas Fanning <tom@ferb.ne.anl.gov>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-07-10 22:23:38 +01:00
Adam Turner
82edc3d385
Rewrite `usage/configuration.rst` (#12537)
- Remove now-removed configuration values
- Use obvious 'unset' defaults for ``project`` and ``author``
- Prefer 'e.g.' to 'ex.'
- Allow non-list sequence types in various configuration values
- Add types and defaults to every confval directive
2024-07-10 21:43:14 +01:00
Adam Turner
a4de250b5a
Add a new `confval` directive to document settings and configuration values (#12536) 2024-07-10 20:44:16 +01:00
Tim Hoffmann
a95d716f7f
Add a class option to the toctree directive (#12524)
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
2024-07-10 11:07:49 +01:00
Adam Turner
d2f1acc0ca
Simplify `Tags` (#12490)
- Use a set to store the list of tags
- Cache evaluated expressions
- Extract locally-defined function into a private method
2024-06-29 10:21:23 +01:00
Ondřej Navrátil
3b3a7d911b
[toctree] Adding warning type/subtype toc.no_title (#12479)
Add warning type and subtype to warning generated in toctree
2024-06-27 23:34:46 +02:00
James Addison
751e9162c0
[maintenance] self-linkcheck the Sphinx documentation. (#12487)
Fixups for a few broken links in the Sphinx documentation, as found using the `linkcheck` builder.
2024-06-27 23:32:50 +02:00
Chris Sewell
953c0097ef
[docs] add icons to admonition titles (#12486)
and also replace ad-hoc "more" icon in quickstart, with using `seealso` admonition
2024-06-27 23:06:52 +02:00
Tim Hoffmann
a53a758d40
DOC: Rewrite installation instructions (#12458)
- Put pip and conda as the most common options first
- Don't distinguish Linux / Windows in the pip commands.
- Replace the venv instructions by a general tip to use environments and link out for details.
- Collect all OS-specific package manager in one section
- Remove the "Windows - Other methods" secion. 
- Move latest development release to a separate entry. 

Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
2024-06-25 12:17:55 +02:00
James Addison
6b237d9a70
[linkcheck] Allow integer for linkcheck_rate_limit_timeout (#12470)
Eliminate type-related warnings when users configure a valid integer value for the `linkcheck_rate_limit_timeout` config setting.

Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
2024-06-24 17:26:24 +00:00
Rafael Fontenelle
2ccae70089
[docs] Fix typos in autodoc.rst (#12469) 2024-06-24 14:48:54 +02:00
Chris Sewell
8f97fd276a
[docs] Improve landing page (#12453)
This commit is intended to improve new user's first-interaction with the Sphinx site:

- Make page header icon/text smaller and not capitalized
- Give min-width to left sidebar (it was getting too small at certain window sizes)
- Replace features list on landing page with admonition boxes, with adaptive layout
- Add landing page "used by" section
- Slightly restructure the Extension section, into Tutorials and How-tos
- Add code to `conf.py` to write HTML write redirect pages for moved documents
- Improve support page, by adding link to Stackoverflow, GH discussion and ReadtheDocs,
  and remove defunct link to libera chat and matplotlib tutorial
2024-06-21 20:12:57 +02:00
Tim Hoffmann
1e77e6bc9a
DOC: Move autodoc setup/usage to extension docs (#12435)
Leaving just the link in the quickstart guide
2024-06-17 11:58:55 +02:00
Tim Hoffmann
4fbd3682d5
DOC: Add autodoc section "Ensuring the code can be imported" (#12426)
This explains the requirements for importablilty (can be found and dependencies can be resolved). It also explains two common approaches how this can be achieved.
2024-06-12 11:43:33 +02:00