Commit Graph

220 Commits

Author SHA1 Message Date
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
Adam Turner
b5b383fd47
Rewrite the "Docutils markup API" page (#12505) 2024-07-03 02:09:15 +01:00
Adam Turner
1887df0b5c
Add reStructuredText parsing functions to `SphinxDirective` (#12492) 2024-07-02 22:14:19 +01:00
Chris Sewell
d130c2e710
[docs] Improve tutorials (#12473)
This commit make it clearer, from the filenames and titles,
what the extension tutorials are intended to teach.
2024-06-27 22:30:03 +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
Chris Sewell
0e3f5b4ab2
[DOCS] Improve events (#12446)
Split the events callback API into a separate document, add a flow graph of the events within the build process, add parameters to the events,
and link the `EnvironmentCollector` docs to the relevant events.

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
2024-06-20 10:40:22 +02:00
Chris Sewell
13b16c9b04
DOCS: hide todo admonitions on RTD (#12442)
`todo` admonitions should not be present in the user-facing documentation (built on ReadTheDocs)
2024-06-19 15:15:31 +02:00
Chris Sewell
37ff33dff7
[builder] type Builder core methods with @final and improve docs (#12436)
This commit:

- annotates the `Builder`'s "core" methods, with [`final`](https://docs.python.org/3/library/typing.html#typing.final)
- adds a UML graph to the Builder API docs
- Adds more methods to the Builder API docs

to make it clearer for extension developers, what is expected from a new builder subclass.
2024-06-19 14:51:20 +02:00
Dimitri Papadopoulos Orfanos
53c31f77b6
🔧 Apply ruff rule ISC001 (#12401) 2024-06-03 08:35:48 +02:00
Adam Turner
e3f0aa9307 Ensure raw strings are used for regular expression patterns 2024-04-09 18:33:42 +01:00
Bénédikt Tran
f44ff30673
[doc] cleanup references and update external URLs (#12182) 2024-03-25 11:39:05 +01:00
Chris Sewell
3bedde26a9
🔧 Ruff format python files within docs folder (#12139)
Remove `docs` files from the `exclude` list, and also add the `preview = false` format config, which is shown to reduce diffs to the current code base
2024-03-19 15:23:57 +01:00
Chris Sewell
b0f096f440
Add show_warning_types configuration variable (#12131)
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
2024-03-19 10:22:28 +01:00
danieleades
f9c8943889
Use `# NoQA` consistently (#11903)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-01-21 20:20:58 +00:00
danieleades
f7fbfaa471
Enable various pydocstyle (D) rules (#11878)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2024-01-14 21:13:46 +00:00
Adam Turner
3ac143c8bf Enable nit-picky mode in `conf.py` 2023-09-21 09:02:58 +01:00
Adam Turner
655bd15749 Adorn top-level files with a '.rst' suffix 2023-09-14 11:08:17 +01:00
Matt Wozniski
43d69755df
Leverage `importlib.reload` for reloading modules (#11679)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
2023-09-13 22:58:35 +01:00
Jorge Leitao
99f9209924
Add summary statistics to the coverage report (#5474)
The current implementation of ``sphinx.ext.coverage`` outputs which
methods,classes, and functions are documented.
This commit adds a short summary of this report in terms of
``documented objects / total number of objects``,
both per module and total.

The purpose of this is to support
a currently not mainstream but relevant use-case:
a coverage report on the number of objects that are documented.

By having the statistics on the report or on the stdout,
a regex expression can capture the coverage percentage
(e.g. ``re.search(r'TOTAL.*?([0-9.]{4,6}\%)', d).group(1)``)
and use it e.g. in another report, a status badge, etc.

Two options were added to the configuration to allow a table
to be printed in the report and/or to stdout.

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
2023-07-28 02:33:42 +01:00
Adam Turner
ad61e41157
Drop support for Python 3.8 (#11511) 2023-07-25 02:07:23 +01:00
James Addison
d15a837c61
Emend hyperlinks within the CHANGES and EXAMPLES (#11506)
* Remove "dead" links
* Update project links to the correct hostnames
2023-07-24 11:49:44 +01:00
Adam Turner
2a9e805206
Remove the deprecated Setuptools integration (#11363) 2023-04-27 01:22:04 +01:00
Adam Turner
7ecf037280 Enable 'nit-picky mode' for Sphinx's documentation
Fix several reference errors throughout the documentation and set
``nitpick_ignore`` in ``doc/conf.py``.
2023-04-06 23:11:39 +01:00
Dmitry Shachnev
54f531e978
Remove obsolete workarounds in `doc/conf.py` (#11250)
Loading jQuery is not needed since January 2023:
https://github.com/readthedocs/readthedocs.org/pull/9861

And exposing app.{info,warn,debug} is not needed since September 2018:
https://github.com/readthedocs/readthedocs-sphinx-ext/pull/51
2023-03-23 21:42:28 +00:00
Daniel Eades
1abb24e309 remove blanket 'noqas' 2022-12-16 16:50:24 +01:00
Jean-François B
2f60b44999 Avoid a cramped LaTeX table column in our own document
This is for the table of the Websupport.get_data() auto-documentation.

Somethink similar perhaps \setlength{\tymin}{1.5cm} at least could be a
global default; the only reason we have not changed it yet is that
perhaps some tables in user projects use really short contents such as
letter.

(what we would want to avoid is narrow columns allowed by hyphenation of
single words; maybe some thinking needed here as \sphinxAtStartPar
renders this hyphenation possible but perhaps even upstream LaTeX has
now made hyphenation of single words work in table cells).
2022-10-30 17:09:30 +01:00
Adam Turner
920828fe35 Run the `pyupgrade` tool 2022-10-17 22:39:09 +01:00
Jean-François B
49c48f5aee
LaTeX: switch to some nicer defaults for tables and code-blocks (#10924) 2022-10-17 11:19:25 +02:00
Adam Turner
e70a0fac6d Merge branch '5.x'
# Conflicts:
#	.github/workflows/main.yml
#	CHANGES
#	sphinx/__init__.py
#	sphinx/domains/c.py
2022-10-16 11:24:18 +01:00
Jean-François B
b5ba1ede2a s/5.2.0/5.3.0 in various code comments as #10759 got merged in 5.3.0 2022-10-12 17:41:39 +02:00
Jean-François B
e7c0881992
LaTeX: support for booktabs-style and zebra-striped tables (#10759)
This is a combination of 2 + 28 + 7 + and some more commits...

* Cherry-pick: Add support for booktabs-style tables to LaTeX builder

* Cherry-pick: Add support for zebra-striped tables to LaTeX builder

Co-authored-by: Stefan Wiehler <stefan.wiehler@missinglinkelectronics.com>

Above work originally initiated by @sephalon (thanks!)

Development refactored and continued by @jfbu

* latex_table_style configuration, support booktabs, colorrows, borderless

Some details:

- Simplify a bit a conditional in the longtable template

  This also puts the target for a longtable with a label but no caption
  above the toprule for better hyperlinking (testing shows hyperlink
  target can not end up alone at bottom of previous page).

- Extend allowed syntax for colour assignments via 'sphinxsetup'

- latex_table_style new configuration value and coloured rows

  For the user interface I tried to look for inspiration in
  https://docutils.sourceforge.io/docs/user/config.html#table-style
  which mentions booktabs and borderless.  They also mention
  captionbelow which we can implement later, now that architecture
  is here.  They don't mention coloured rows.

- Test on our own document... looks fine!

- Work-around an incompatibility of \cline with row colours

- Reverse priority of classes to allow overruling booktabs by standard
  after parsing source but before letting LaTeX writer act

- Closes #8220

  Commit
  bb859c6696
  already improved a bit, this finishes it (as :rst:dir:`rst-class` was
  actually not linking to anywhere).

- Let booktabs style defaults to *not* using \cmidrule.  They actually
  don't make much sense there, as all \hline's are removed.

- Add \sphinxnorowcolor which allows construct such as this one in
  a tabularcolumns directive:

    >{\columncolor{blue}\sphinxnorowcolor}

  else LaTeX always overrides column colour by row colour

- Add TableMergeColorHeader, TableMergeColorOdd, TableMergeColorEven
  so single-row merged cells can be styled especially

- Extend row colours to all header rows not only the first one
  (all header rows will share same colour settings)

- Auto-adjust to a no '|'-colspec for optimal handling of merged cell

- Add \sphinxcolorblend

- Workaround LaTeX's \cline features and other grid tables matters

- Add \sphinxbuildwarning for important warnings

- Fix some white gaps in merged cells of tables with vlines and
  colorrows

- Work around LaTeX's \cline serious deficiencies for complex grid
  tables

  This commit corrects \cline badly impacting vertical spacing and
  making tables look even more cramped as they usually are in LaTeX
  (although one sees it clearly only with \arrarrulewidth a bit more
  than the LaTeX default of 0.4pt).

  Most importantly this commit solves the problem that \cline's got
  masked by colour panels from the row below.

- Update CHANGES for PR #10759

- Improve documentation of new latex_table_style regarding colours
2022-10-12 17:15:40 +02:00
Adam Turner
f01d50d695 Merge branch '5.x'
# Conflicts:
#	CHANGES
#	doc/conf.py
#	sphinx/__init__.py
#	sphinx/builders/html/__init__.py
#	sphinx/domains/python.py
#	tests/test_build_html.py
2022-09-25 21:36:30 +01:00
Adam Turner
c7c0e4048d Split out sphinx_highlight.js 2022-09-24 15:10:57 +01:00
Adam Turner
a4d41aa889 Merge branch '5.x' 2022-07-17 21:53:12 +01:00
Jean-François B
d737608591
Merge pull request #10648 from jfbu/latex_enhancedboxes
LaTeX: box padding (t,r,b,l), borders (t,r,b,l), shadows (x,y) or radii
2022-07-14 11:19:48 +02:00
Jean-François B
64647ca55f LaTeX: enhanced boxes with padding, borders, shadows, rounded corners
- LaTeX: box padding (t,r,b,l), borders (t,r,b,l), shadows (x,y) or radii

- LaTeX: fix #10650 via usage of our own sophisticated \fcolorbox

- LaTeX: user interface via 'sphinxsetup' to enhanced code-blocks frames

- LaTeX: user interface via 'sphinxsetup' to enhanced topic boxes

- LaTeX: CSS-named-alikes 'sphinxsetup' options for code-blocks and
  topics

- LaTeX: CSS-named-alikes 'sphinxsetup' keys for warning type notices
  (fix #10651)

- LaTeX: documentation of the new CSS-like options

- LaTeX: remove #10619 documentation, as the #10619 added
  shadowBorderColor and shadowShadowColor now named respectively:

  aside.topic_border-TeXcolor and aside.topic_box-shadow-TeXcolor

- LaTeX: use div.topic option prefix and not aside.topic for CSS-like
  options

- LaTeX: keep the implicit legacy padding of warning type boxes as
  default behaviour
2022-07-14 11:08:28 +02:00
Adam Turner
1e3ade55fe Merge branch '5.x' 2022-07-10 23:05:23 +01:00
Adam Turner
9112cfeb8d
Refresh the Sphinx13 theme (#10652) 2022-07-10 22:48:15 +01:00
Jean-François B
4dbb62b9cd LaTeX: optional rounded corners for framing of code-blocks
Via a new configuration verbatimradius of 'sphinxsetup', which defaults
to 0pt.

If this dimension is non zero, the LaTeX package pict2e will be loaded
to help construct frames with rounded corners for code-blocks.  And if
the LaTeX package pict2e was not found, a LaTeX warning is issued during
PDF build.
2022-07-05 09:56:40 +02:00
Adam Turner
b26bf0320c
Add underscore.js to the sphinx13 theme (#10588) 2022-06-19 23:12:38 +01:00
Takeshi KOMIYA
521a47b033 Fix #10574: Failed to search on sphinx-doc.org (again)
To make RtD search available, this adds jQuery patches on old Sphinx to
sphinx-doc.org.
2022-06-19 19:26:18 +09:00
Takeshi KOMIYA
a06c49105b Fix #10574: Failed to search on sphinx-doc.org
Since 6.0, jQuery has not been loaded by default.  It affects to the
search feature of RtD.  This loads jQuery again to make it available.
2022-06-19 18:35:45 +09:00
Adam Turner
ce31e1c0c7
Remove deprecated items for Sphinx 6.0 (#10471) 2022-06-16 21:05:37 +01:00
Takeshi KOMIYA
004012b6df Merge branch '4.x' into 5.0.x 2022-05-28 23:17:46 +09:00
Takeshi KOMIYA
721bc00d2b Update URL for requests 2022-05-28 23:04:55 +09:00
Adam Turner
ec0c13c26d Don't use deprecated setup.py build_sphinx 2022-04-16 19:08:27 +01:00
Takeshi KOMIYA
2db180da70 Merge branch '4.x' 2022-03-27 19:47:11 +09:00
Takeshi KOMIYA
7ffc606e0c doc: URL of requests has changed now 2022-03-27 16:13:15 +09:00
Martin Fischer
eab7efc333 doc: Linkify issue numbers in changelog to GitHub 2022-01-08 15:57:16 +01:00