You can subscribe to this list here.
| 2002 |
Jan
|
Feb
|
Mar
|
Apr
(5) |
May
(27) |
Jun
(22) |
Jul
(72) |
Aug
(82) |
Sep
(86) |
Oct
(138) |
Nov
(100) |
Dec
(62) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2003 |
Jan
(122) |
Feb
(147) |
Mar
(92) |
Apr
(82) |
May
(101) |
Jun
(153) |
Jul
(37) |
Aug
(34) |
Sep
(46) |
Oct
(46) |
Nov
(6) |
Dec
(38) |
| 2004 |
Jan
(64) |
Feb
(81) |
Mar
(36) |
Apr
(194) |
May
(329) |
Jun
(272) |
Jul
(68) |
Aug
(74) |
Sep
(150) |
Oct
(57) |
Nov
(62) |
Dec
(63) |
| 2005 |
Jan
(78) |
Feb
(30) |
Mar
(137) |
Apr
(78) |
May
(54) |
Jun
(122) |
Jul
(72) |
Aug
(110) |
Sep
(80) |
Oct
(75) |
Nov
(125) |
Dec
(79) |
| 2006 |
Jan
(100) |
Feb
(15) |
Mar
(41) |
Apr
(67) |
May
(30) |
Jun
(11) |
Jul
(14) |
Aug
(22) |
Sep
(20) |
Oct
(14) |
Nov
(11) |
Dec
(15) |
| 2007 |
Jan
(17) |
Feb
(16) |
Mar
(35) |
Apr
(21) |
May
(33) |
Jun
(50) |
Jul
(12) |
Aug
(7) |
Sep
(2) |
Oct
(6) |
Nov
(5) |
Dec
(2) |
| 2008 |
Jan
(14) |
Feb
(20) |
Mar
(35) |
Apr
(9) |
May
(57) |
Jun
(21) |
Jul
(42) |
Aug
(4) |
Sep
(13) |
Oct
(76) |
Nov
(40) |
Dec
(55) |
| 2009 |
Jan
(26) |
Feb
(15) |
Mar
(3) |
Apr
(67) |
May
(32) |
Jun
(39) |
Jul
(59) |
Aug
(31) |
Sep
(59) |
Oct
(64) |
Nov
(21) |
Dec
(10) |
| 2010 |
Jan
(21) |
Feb
(3) |
Mar
(116) |
Apr
(33) |
May
(9) |
Jun
(28) |
Jul
(21) |
Aug
(23) |
Sep
(146) |
Oct
(70) |
Nov
(31) |
Dec
(57) |
| 2011 |
Jan
(33) |
Feb
(22) |
Mar
(11) |
Apr
(21) |
May
(51) |
Jun
(47) |
Jul
(35) |
Aug
(26) |
Sep
(25) |
Oct
(34) |
Nov
(61) |
Dec
(51) |
| 2012 |
Jan
(75) |
Feb
(31) |
Mar
(26) |
Apr
(16) |
May
(24) |
Jun
(24) |
Jul
(31) |
Aug
(46) |
Sep
(36) |
Oct
(28) |
Nov
(37) |
Dec
(21) |
| 2013 |
Jan
(16) |
Feb
(56) |
Mar
(31) |
Apr
(44) |
May
(45) |
Jun
(29) |
Jul
(38) |
Aug
(18) |
Sep
(12) |
Oct
(16) |
Nov
(21) |
Dec
(11) |
| 2014 |
Jan
(13) |
Feb
(14) |
Mar
(28) |
Apr
(7) |
May
(72) |
Jun
(33) |
Jul
(21) |
Aug
(1) |
Sep
(6) |
Oct
(14) |
Nov
(18) |
Dec
(22) |
| 2015 |
Jan
(23) |
Feb
(108) |
Mar
(76) |
Apr
(114) |
May
(60) |
Jun
(9) |
Jul
(8) |
Aug
(9) |
Sep
(42) |
Oct
(9) |
Nov
|
Dec
(7) |
| 2016 |
Jan
(6) |
Feb
(15) |
Mar
(7) |
Apr
|
May
(33) |
Jun
(3) |
Jul
(19) |
Aug
(12) |
Sep
(6) |
Oct
(16) |
Nov
(17) |
Dec
(125) |
| 2017 |
Jan
(66) |
Feb
(98) |
Mar
(29) |
Apr
(32) |
May
(63) |
Jun
(98) |
Jul
(26) |
Aug
(33) |
Sep
(19) |
Oct
(77) |
Nov
(31) |
Dec
(27) |
| 2018 |
Jan
(32) |
Feb
(11) |
Mar
(5) |
Apr
(12) |
May
(4) |
Jun
(9) |
Jul
(9) |
Aug
(13) |
Sep
(11) |
Oct
(6) |
Nov
(23) |
Dec
(2) |
| 2019 |
Jan
(26) |
Feb
(12) |
Mar
(20) |
Apr
(18) |
May
(7) |
Jun
(22) |
Jul
(81) |
Aug
(129) |
Sep
(32) |
Oct
(18) |
Nov
(11) |
Dec
(44) |
| 2020 |
Jan
(19) |
Feb
(10) |
Mar
(38) |
Apr
(4) |
May
(9) |
Jun
(15) |
Jul
(29) |
Aug
(79) |
Sep
(12) |
Oct
(22) |
Nov
(10) |
Dec
(37) |
| 2021 |
Jan
(16) |
Feb
(14) |
Mar
(20) |
Apr
(100) |
May
(21) |
Jun
(19) |
Jul
(13) |
Aug
(13) |
Sep
(37) |
Oct
(112) |
Nov
(64) |
Dec
(22) |
| 2022 |
Jan
(209) |
Feb
(38) |
Mar
(11) |
Apr
(10) |
May
(55) |
Jun
(104) |
Jul
(35) |
Aug
(10) |
Sep
(21) |
Oct
(21) |
Nov
(50) |
Dec
(12) |
| 2023 |
Jan
(6) |
Feb
|
Mar
(3) |
Apr
(41) |
May
(48) |
Jun
(9) |
Jul
(6) |
Aug
(25) |
Sep
(3) |
Oct
(22) |
Nov
(56) |
Dec
(12) |
| 2024 |
Jan
(5) |
Feb
(5) |
Mar
(38) |
Apr
(62) |
May
(12) |
Jun
(10) |
Jul
(3) |
Aug
(59) |
Sep
(2) |
Oct
(36) |
Nov
(14) |
Dec
(3) |
| 2025 |
Jan
(5) |
Feb
(19) |
Mar
(7) |
Apr
(65) |
May
(11) |
Jun
(13) |
Jul
(46) |
Aug
(27) |
Sep
(33) |
Oct
(1) |
Nov
(2) |
Dec
(15) |
| 2026 |
Jan
(13) |
Feb
|
Mar
(1) |
Apr
(3) |
May
(10) |
Jun
(7) |
Jul
(1) |
Aug
(4) |
Sep
(7) |
Oct
(2) |
Nov
(5) |
Dec
|
|
From: Günter M. <mi...@us...> - 2026-11-12 12:46:23
|
- **status**: closed-accepted --> open-fixed - **Comment**: The Backwards Compatibiltiy Policy was published in [r10332]. Keeping this ticket open for future discussions of [EP 10](https://docutils.sourceforge.io/docs/eps/ep-010.html#top). --- **[feature-requests:#89] Public API, versioning, and deprecation** **Status:** open-fixed **Group:** Default **Created:** Sun Jan 16, 2022 01:39 AM UTC by Adam Turner **Last Updated:** Thu Nov 12, 2026 12:42 PM UTC **Owner:** nobody As requested by @milde in https://sourceforge.net/p/docutils/bugs/441/#7043/cdb8/8742/6e7f I'm opening this issue to allow for discussion on Docutils' public API, versioning policy, and deprecation. [Enhancement proposal 10](https://docutils.sourceforge.io/docs/eps/ep-010.html) summarizes the discussion. It will be updated with new insights and decisions until a consensus is found. This also relates to FR 87 on type annotations. From Günter, > The idea is to reconcile the reality (Docutils is used as if it were mature) and the version number (<1) once the API sufficiently defined a deprecation policy is agreed. The only text I can find on library versioning is at https://docutils.sourceforge.io/docs/dev/policies.html#version-identification, excerpt below: > **Major releases** (x.0, e.g. 1.0) will be rare, and will represent major changes in API, functionality, or commitment. The major number will be bumped to 1 when the project is feature-complete, and may be incremented later if there is a major change in the design or API. When Docutils reaches version 1.0, the major APIs will be considered frozen. For details, see the `backwards compatibility policy`_. > Releases that change the minor number (x.y, e.g. 0.5) will be **feature releases**; new features from the `Docutils core`_ will be included. > Releases that change the micro number (x.y.z, e.g. 0.4.1) will be **bug-fix releases**. No new features will be introduced in these releases; only bug fixes will be included. The proposed backwards compatability policy reads: > Docutils' backwards compatibility policy follows the rules for Python in PEP 387. ... The scope of the public API is laid out at the start of the backwards compatibility rules I propose two modifications to the policies, which will make future changes to Docutils easier to review and reason about, for project members as well as outside contributors. Firstly, I propose adopting a formal versioning "system" such as Sematic Versioning ([SemVer](https://semver.org/)) or Calendar Versioning ([CalVer](https://calver.org/)). Semantic versioning is nearly identical to the current versioning policy, and has the benefit of being a known quantity, reducing misunderstandings. A potential phrasing would be: **"Docutils follows SemVer. All changes must also follow the backwards compatability policy."** What this does change is that the API is never considered complete, as in the original phrasing. Docutils [isn't slated for inclusion](https://www.python.org/dev/peps/pep-0258/#rejection-notice) in the standard library any more, and there will always be potential improvements and changes -- new parsers, new node types, changes in the HTML specification, et cetera. The 1.0 release then does not need to be a "big deal", and future breaking changes can go to 2.0, 3.0, etc -- setuptools is now on `60.5.0`! Semantic versioning does have some drawbacks (https://snarky.ca/why-i-dont-like-semver/), so projects like pip have adopted calendar based versioning -- the major version is the year (22), and the minor version is either the current month or an increasing number. This relies on strong documentation and changelogs, so that when users upgrade it is obvious what changed (the idea being that every change breaks someone, so there is no contract that version numbers within a certain range mean no breakage). Luckily, Docutils has a good culture around changelogs and histories etc, so this would be easy to adopt. ______ I also suggest enumerating all modules, classes, and functions that form the public API. The current backwards compatability policy references PEP 387, which is specifically for the Python project itself. Checking through the documentation on every change to identify if a name is public or private is error prone (we are all human, and can miss things with no malintent) and time consuming. At the very least I would suggest, `docutils.nodes`, the reader/writer/parser aliases, `docutils.core`, and the front end tools. (I'm happy to write out the full list if you give me modules/etc that should be part of the public API). It would also be useful to identify what parts of Docutils large downstream consumers use, and either create higher level abstractions or mark those as public API. (I would suggest Sphinx and MyST-parser). It is also the [established practice](https://www.python.org/dev/peps/pep-0008/#descriptive-naming-styles) to mark names as private by prefixing them with an underscore. I suggest adopting this, as it gives strong guidance to downstream library authors what Docutils considers private and public. Making a private name public is far easier than going through a deprecation cycle for the reverse. I'd suggest adding the ability to have exceptions to the policy, with removal after one minor version. My full suggested text is: **"Removal or significant alteration of any members of the public API will only take place after the behaviour has been marked as deprecated for two minor releases. Certain changes may have a shorter deprecation period of one minor release. This requires at least two project members to be in favour of doing so, and no members against.** **Changes that may affect end-users (e.g. by requiring changes to the configuration file or potentially breaking custom style sheets) should be announced with a FutureWarning."** This post is intentionally opinionated so as to provide something to talk over / edit -- I'm not massively attached to any one thing! A ---- for reference, amongst others, I took inspiration from: https://setuptools.pypa.io/en/latest/development/releases.html https://pip.pypa.io/en/latest/development/release-process/ https://numpy.org/neps/nep-0023-backwards-compatibility.html --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-11-12 12:42:46
|
- **status**: open --> closed-accepted - **Comment**: Published in [r10332]. https://docutils.sourceforge.io/docs/dev/policies.html#backwards-compatibility-policy --- **[feature-requests:#89] Public API, versioning, and deprecation** **Status:** closed-accepted **Group:** Default **Created:** Sun Jan 16, 2022 01:39 AM UTC by Adam Turner **Last Updated:** Thu Apr 09, 2026 06:40 PM UTC **Owner:** nobody As requested by @milde in https://sourceforge.net/p/docutils/bugs/441/#7043/cdb8/8742/6e7f I'm opening this issue to allow for discussion on Docutils' public API, versioning policy, and deprecation. [Enhancement proposal 10](https://docutils.sourceforge.io/docs/eps/ep-010.html) summarizes the discussion. It will be updated with new insights and decisions until a consensus is found. This also relates to FR 87 on type annotations. From Günter, > The idea is to reconcile the reality (Docutils is used as if it were mature) and the version number (<1) once the API sufficiently defined a deprecation policy is agreed. The only text I can find on library versioning is at https://docutils.sourceforge.io/docs/dev/policies.html#version-identification, excerpt below: > **Major releases** (x.0, e.g. 1.0) will be rare, and will represent major changes in API, functionality, or commitment. The major number will be bumped to 1 when the project is feature-complete, and may be incremented later if there is a major change in the design or API. When Docutils reaches version 1.0, the major APIs will be considered frozen. For details, see the `backwards compatibility policy`_. > Releases that change the minor number (x.y, e.g. 0.5) will be **feature releases**; new features from the `Docutils core`_ will be included. > Releases that change the micro number (x.y.z, e.g. 0.4.1) will be **bug-fix releases**. No new features will be introduced in these releases; only bug fixes will be included. The proposed backwards compatability policy reads: > Docutils' backwards compatibility policy follows the rules for Python in PEP 387. ... The scope of the public API is laid out at the start of the backwards compatibility rules I propose two modifications to the policies, which will make future changes to Docutils easier to review and reason about, for project members as well as outside contributors. Firstly, I propose adopting a formal versioning "system" such as Sematic Versioning ([SemVer](https://semver.org/)) or Calendar Versioning ([CalVer](https://calver.org/)). Semantic versioning is nearly identical to the current versioning policy, and has the benefit of being a known quantity, reducing misunderstandings. A potential phrasing would be: **"Docutils follows SemVer. All changes must also follow the backwards compatability policy."** What this does change is that the API is never considered complete, as in the original phrasing. Docutils [isn't slated for inclusion](https://www.python.org/dev/peps/pep-0258/#rejection-notice) in the standard library any more, and there will always be potential improvements and changes -- new parsers, new node types, changes in the HTML specification, et cetera. The 1.0 release then does not need to be a "big deal", and future breaking changes can go to 2.0, 3.0, etc -- setuptools is now on `60.5.0`! Semantic versioning does have some drawbacks (https://snarky.ca/why-i-dont-like-semver/), so projects like pip have adopted calendar based versioning -- the major version is the year (22), and the minor version is either the current month or an increasing number. This relies on strong documentation and changelogs, so that when users upgrade it is obvious what changed (the idea being that every change breaks someone, so there is no contract that version numbers within a certain range mean no breakage). Luckily, Docutils has a good culture around changelogs and histories etc, so this would be easy to adopt. ______ I also suggest enumerating all modules, classes, and functions that form the public API. The current backwards compatability policy references PEP 387, which is specifically for the Python project itself. Checking through the documentation on every change to identify if a name is public or private is error prone (we are all human, and can miss things with no malintent) and time consuming. At the very least I would suggest, `docutils.nodes`, the reader/writer/parser aliases, `docutils.core`, and the front end tools. (I'm happy to write out the full list if you give me modules/etc that should be part of the public API). It would also be useful to identify what parts of Docutils large downstream consumers use, and either create higher level abstractions or mark those as public API. (I would suggest Sphinx and MyST-parser). It is also the [established practice](https://www.python.org/dev/peps/pep-0008/#descriptive-naming-styles) to mark names as private by prefixing them with an underscore. I suggest adopting this, as it gives strong guidance to downstream library authors what Docutils considers private and public. Making a private name public is far easier than going through a deprecation cycle for the reverse. I'd suggest adding the ability to have exceptions to the policy, with removal after one minor version. My full suggested text is: **"Removal or significant alteration of any members of the public API will only take place after the behaviour has been marked as deprecated for two minor releases. Certain changes may have a shorter deprecation period of one minor release. This requires at least two project members to be in favour of doing so, and no members against.** **Changes that may affect end-users (e.g. by requiring changes to the configuration file or potentially breaking custom style sheets) should be announced with a FutureWarning."** This post is intentionally opinionated so as to provide something to talk over / edit -- I'm not massively attached to any one thing! A ---- for reference, amongst others, I took inspiration from: https://setuptools.pypa.io/en/latest/development/releases.html https://pip.pypa.io/en/latest/development/release-process/ https://numpy.org/neps/nep-0023-backwards-compatibility.html --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-11-12 12:38:37
|
- **Group**: --> Default - **Priority**: 5 --> 3 --- **[feature-requests:#21] Add :valueasclass: option to role directive** **Status:** open **Group:** Default **Created:** Sun Mar 14, 2010 03:31 PM UTC by Jeffrey C. Jacobs **Last Updated:** Mon Jun 30, 2014 10:21 PM UTC **Owner:** nobody It would be nice, for the purposes of a more flexible form of indexing such that all text adorned with a role that had this property would, in addition to its standard role classes, receive a class of the form role<text> in it's class list. This would allow for easy dynamic HTML using CSS for any such text markup. In other words: .. role:: keyword :valueasclass: If you remember :keyword:\`apple\` or :keyword:\`pear\`, you're almost there\! This would render similar to: The output would be <paragraph> If you remember <keyword class='roleapple'> apple or <keyword class='rolepear'> , you're almost there\! Where further CSS could highlight text of class roleapple or rolepear as necessary. --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-11-12 12:26:25
|
- **status**: open --> closed-accepted - **Comment**: Committed in [r10411]. --- **[patches:#217] AI policy** **Status:** closed-accepted **Group:** None **Created:** Sat Sep 26, 2026 10:51 AM UTC by Günter Milde **Last Updated:** Sat Sep 26, 2026 10:56 AM UTC **Owner:** nobody I suggest to add the following paragraph about copyright responsibilities and section about use of AI for contributions to Docutils to the "Docutils Project Policies". It is an adapted and shortened version of the Sphinx AI policy which itself is based on the AI policy of NumPy and SciPy which are based on SymPy's [AI Generated Code and Communication Policy](https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html). --- a/docutils/docs/dev/policies.rst +++ b/docutils/docs/dev/policies.rst @@ -153,6 +153,11 @@ the project for inclusion (via Subversion, SourceForge trackers, mailing lists, or private email) are assumed to be in the public domain as well. +Contributors must ensure their contribution does not infringe on the +copyright of others and reference the copyright holder and license of +code parts under a compatible open-source license. We reserve the right +to reject any contributions where the copyright is in question. + Any new files contributed to the project should clearly state their intentions regarding copyright, in one of the following ways: @@ -177,6 +182,58 @@ intentions regarding copyright, in one of the following ways: __ ../../licenses/BSD-2-Clause.rst +AI Policy +========= + +All contributors must disclose whether AI [#ai]_ has been used to assist in +the development of their contributions. If so, they must document which +tool(s) have been used, how they were used, and specify what code or text +is AI generated. +We will reject contributions without accompanying AI disclosure. + +The use of an AI agent that writes code and then submits a patch +autonomously is not permitted. A human must check any generated code and +submit the patch. Please do not waste developers' time by submitting +code that is fully or mostly generated by AI and doesn't meet our +standards. + +Contributors are responsible for any code they submit for inclusion +in Docutils, regardless of whether it was manually written or generated +by AI. They must understand and be able to explain the submitted code as +well as the existing related code. It is not acceptable to submit a patch +that is not understood or cannot be explained by the submitter. +When documenting the contribution, do not use AI to automatically generate +comments or issue descriptions or update the user documentation. + +.. sidebar:: Further Reading + + - `Sphinx AI policy + <https://www.sphinx-doc.org/en/master/internals/ai-policy.html>`_ + - `LLVM AI tool policy <https://llvm.org/docs/AIToolPolicy.html>`_ + - `Open source AI contribution policies + <https://github.com/melissawm/open-source-ai-contribution-policies>`_ + - `Scientific Python community considerations around AI + <https://blog.scientific-python.org/scientific-python/ + community-considerations-around-ai/>`_ + - `Python developer's guide to AI tools + <https://devguide.python.org/getting-started/ai-tools/index.html>`_ + +When interacting with the maintainers (forums, discussions, issues, etc.) +do not use AI to speak for you, except for translation or grammar +editing. If the developers want to chat with a chatbot, they can do so +themselves. Human-to-human communication is essential for an open source +community to thrive. + +We thank the SymPy developers, whose `AI Generated Code and Communication +Policy`__ this section was adapted from. + +.. [#ai] "AI" herein refers to generative AI tools like large language + models (LLMs) that can generate, edit, and review software code, + images, or texts. + +__ https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html + + .. _Subversion Repository: Repository ~~~ diff --- a/docutils/docs/dev/policies.rst +++ b/docutils/docs/dev/policies.rst @@ -153,6 +153,11 @@ the project for inclusion (via Subversion, SourceForge trackers, mailing lists, or private email) are assumed to be in the public domain as well. +Contributors must ensure their contribution does not infringe on the +copyright of others and reference the copyright holder and license of +code parts under a compatible open-source license. We reserve the right +to reject any contributions where the copyright is in question. + Any new files contributed to the project should clearly state their intentions regarding copyright, in one of the following ways: @@ -177,6 +182,58 @@ intentions regarding copyright, in one of the following ways: __ ../../licenses/BSD-2-Clause.rst +AI Policy +========= + +All contributors must disclose whether AI [#ai]_ has been used to assist in +the development of their contributions. If so, they must document which +tool(s) have been used, how they were used, and specify what code or text +is AI generated. +We will reject contributions without accompanying AI disclosure. + +The use of an AI agent that writes code and then submits a patch +autonomously is not permitted. A human must check any generated code and +submit the patch. Please do not waste developers' time by submitting +code that is fully or mostly generated by AI and doesn't meet our +standards. + +Contributors are responsible for any code they submit for inclusion +in Docutils, regardless of whether it was manually written or generated +by AI. They must understand and be able to explain the submitted code as +well as the existing related code. It is not acceptable to submit a patch +that is not understood or cannot be explained by the submitter. +When documenting the contribution, do not use AI to automatically generate +comments or issue descriptions or update the user documentation. + +.. sidebar:: Further Reading + + - `Sphinx AI policy + <https://www.sphinx-doc.org/en/master/internals/ai-policy.html>`_ + - `LLVM AI tool policy <https://llvm.org/docs/AIToolPolicy.html>`_ + - `Open source AI contribution policies + <https://github.com/melissawm/open-source-ai-contribution-policies>`_ + - `Scientific Python community considerations around AI + <https://blog.scientific-python.org/scientific-python/ + community-considerations-around-ai/>`_ + - `Python developer's guide to AI tools + <https://devguide.python.org/getting-started/ai-tools/index.html>`_ + +When interacting with the maintainers (forums, discussions, issues, etc.) +do not use AI to speak for you, except for translation or grammar +editing. If the developers want to chat with a chatbot, they can do so +themselves. Human-to-human communication is essential for an open source +community to thrive. + +We thank the SymPy developers, whose `AI Generated Code and Communication +Policy`__ this section was adapted from. + +.. [#ai] "AI" herein refers to generative AI tools like large language + models (LLMs) that can generate, edit, and review software code, + images, or texts. + +__ https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html + + .. _Subversion Repository: Repository ~~~ --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: engelbert g. <gr...@us...> - 2026-11-08 20:06:52
|
two problems (no audience i assume) 1. the markup has to be explicit , i dislike lexing/parsing an already split text along title-reference and pep-reference a manpage-reference maybe some short alias# ~~~ see :manpage-reference:`groff (1)` ~~~ the manpage writer then can make it ~~~ .MR groff 1 ~~~ and html and latex ... different? --- **[bugs:#482] manpage: section numbers wrongly in boldface in "See also" section** **Status:** open **Labels:** manpage writer **Created:** Wed Mar 27, 2024 01:22 AM UTC by G. Branden Robinson **Last Updated:** Wed May 13, 2026 07:02 PM UTC **Owner:** engelbert gruber The parenthesized section number of a man page document should be rendered upright at normal weight, not in boldface. This appears to be an unintentional defect in the manpage writer. Here's a snippet of _rst2man_ output. ~~~ .SH SEE ALSO .INDENT 0.0 .TP .B \fIgroff_man_style\fP(7) is a reference to the \fIgroff\fP \fIman\fP macro language, with much advice for document authors. .TP .B \fImandoc\fP(1) is a non\-\fIroff\fP\-based system for formatting man pages. .UNINDENT ~~~ It's pretty confusing to humans to mix font selection escape sequences with _man_ font macros. (I also think that macros should be used in preference to formatter requests or escape sequences wherever possible, but I acknowledge that this is a much bigger challenge for document format conversion programs than for human writers.) Here's what I propose when formatting a man page cross reference, in case you're doing any pattern matching to detect them. ~~~ .TP .B \fIgroff_man_style\fP\R(7)\fP ~~~ If you're _not_ doing pattern matching to detect man page cross references, the problem may be harder. Here's my rST input for the foregoing. ~~~ See also ======== *groff_man_style*\(7) is a reference to the *groff* *man* macro language, with much advice for document authors. *mandoc*\(1) is a non-*roff*-based system for formatting man pages. ~~~ It appears to me that the decision to set the paragraph tag (definition list headword) in bold was _rst2man_'s; it was not derived from any formatting in the rST source document. I humbly suggest reconsidering that choice, and let rST document authors select whatever degree of typographic emphasis for the paragraph tag/definition list headword they desire. In fact it appears to be that they can already do so, so the ``B`` call may just be getting in the way. --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-10-16 22:13:12
|
- **status**: pending-moreinfo --> open-fixed - **Comment**: The `<line_break>` element is implemented in [r10408]. --- **[feature-requests:#101] New "doctree" element for hard line breaks.** **Status:** open-fixed **Group:** Default **Created:** Tue Dec 12, 2023 08:16 PM UTC by Günter Milde **Last Updated:** Mon Dec 15, 2025 11:32 AM UTC **Owner:** nobody Not providing for "hard line break elements" in the Docutils document model and reStructuredText syntax was a deliberate decision at the time these two were devised. However, times have changed and there are new arguments and use-cases for hard line breaks. (cf. the [comments in #85](https://sourceforge.net/p/docutils/feature-requests/85/#d02b)). Something like a `<br>` inline node or special handling of `<inline class=line-break>` inline nodes may be considered. The latter would not change the document model and could be implemented at the writer level or via stylesheet rules. Whether to add a reStructuredText syntax for hard line breaks can be decided independently. The current rules require a non-white character in a role defined with `.. role:: line-break`. --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-10-03 20:38:06
|
- **status**: open --> open-fixed - **Comment**: The `figalign` option and the `legacy-figure-align` setting are added in in [r10407]. --- **[feature-requests:#114] Inconsistent handling of "figure" directive option "align".** **Status:** open-fixed **Group:** Default **Labels:** reStructuredText **Created:** Wed Apr 23, 2025 07:22 PM UTC by Günter Milde **Last Updated:** Wed Apr 23, 2025 07:22 PM UTC **Owner:** nobody The [figure](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure) directive passes all options that are supported by the "image" directive **except `align`** to the included image: * `width` sets the image width, `figwidth` sets the figure width, * `class` sets image class values, `figclass` sets figure class values, * `name` sets a reference name for the image, `figname` sets a reference name for the figure. but * `align` sets the alignment of the figure and there is no option to set the alignment of an image in the figure.¹ ¹ As a workaround, the image alignment can be set passing the special values "align-left", "align-right", or "align-center" to the `class` option. Suggestion: * Use `align` for image alignment and the new option `figalign` for figure alignment. * Provide a new configuration setting `legacy-figure-align` for the rST parser that switches to the current behaviour for backwards compatibility. The default value of this setting would be "True" and change at a later stage. --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-09-26 10:56:59
|
- Description has changed: Diff: ~~~~ --- old +++ new @@ -1,7 +1,6 @@ I suggest to add the following paragraph about copyright responsibilities and section about use of AI for contributions to Docutils to the "Docutils Project Policies". -It is an adapted and shortened version of the Sphinx AI policy which itself is based on the AI policy of NumPy and SciPy which are based on SymPy's [AI Generated Code and Communication -+Policy](https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html). +It is an adapted and shortened version of the Sphinx AI policy which itself is based on the AI policy of NumPy and SciPy which are based on SymPy's [AI Generated Code and Communication Policy](https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html). --- a/docutils/docs/dev/policies.rst +++ b/docutils/docs/dev/policies.rst ~~~~ --- **[patches:#217] AI policy** **Status:** open **Group:** None **Created:** Sat Sep 26, 2026 10:51 AM UTC by Günter Milde **Last Updated:** Sat Sep 26, 2026 10:56 AM UTC **Owner:** nobody I suggest to add the following paragraph about copyright responsibilities and section about use of AI for contributions to Docutils to the "Docutils Project Policies". It is an adapted and shortened version of the Sphinx AI policy which itself is based on the AI policy of NumPy and SciPy which are based on SymPy's [AI Generated Code and Communication Policy](https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html). --- a/docutils/docs/dev/policies.rst +++ b/docutils/docs/dev/policies.rst @@ -153,6 +153,11 @@ the project for inclusion (via Subversion, SourceForge trackers, mailing lists, or private email) are assumed to be in the public domain as well. +Contributors must ensure their contribution does not infringe on the +copyright of others and reference the copyright holder and license of +code parts under a compatible open-source license. We reserve the right +to reject any contributions where the copyright is in question. + Any new files contributed to the project should clearly state their intentions regarding copyright, in one of the following ways: @@ -177,6 +182,58 @@ intentions regarding copyright, in one of the following ways: __ ../../licenses/BSD-2-Clause.rst +AI Policy +========= + +All contributors must disclose whether AI [#ai]_ has been used to assist in +the development of their contributions. If so, they must document which +tool(s) have been used, how they were used, and specify what code or text +is AI generated. +We will reject contributions without accompanying AI disclosure. + +The use of an AI agent that writes code and then submits a patch +autonomously is not permitted. A human must check any generated code and +submit the patch. Please do not waste developers' time by submitting +code that is fully or mostly generated by AI and doesn't meet our +standards. + +Contributors are responsible for any code they submit for inclusion +in Docutils, regardless of whether it was manually written or generated +by AI. They must understand and be able to explain the submitted code as +well as the existing related code. It is not acceptable to submit a patch +that is not understood or cannot be explained by the submitter. +When documenting the contribution, do not use AI to automatically generate +comments or issue descriptions or update the user documentation. + +.. sidebar:: Further Reading + + - `Sphinx AI policy + <https://www.sphinx-doc.org/en/master/internals/ai-policy.html>`_ + - `LLVM AI tool policy <https://llvm.org/docs/AIToolPolicy.html>`_ + - `Open source AI contribution policies + <https://github.com/melissawm/open-source-ai-contribution-policies>`_ + - `Scientific Python community considerations around AI + <https://blog.scientific-python.org/scientific-python/ + community-considerations-around-ai/>`_ + - `Python developer's guide to AI tools + <https://devguide.python.org/getting-started/ai-tools/index.html>`_ + +When interacting with the maintainers (forums, discussions, issues, etc.) +do not use AI to speak for you, except for translation or grammar +editing. If the developers want to chat with a chatbot, they can do so +themselves. Human-to-human communication is essential for an open source +community to thrive. + +We thank the SymPy developers, whose `AI Generated Code and Communication +Policy`__ this section was adapted from. + +.. [#ai] "AI" herein refers to generative AI tools like large language + models (LLMs) that can generate, edit, and review software code, + images, or texts. + +__ https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html + + .. _Subversion Repository: Repository ~~~ diff --- a/docutils/docs/dev/policies.rst +++ b/docutils/docs/dev/policies.rst @@ -153,6 +153,11 @@ the project for inclusion (via Subversion, SourceForge trackers, mailing lists, or private email) are assumed to be in the public domain as well. +Contributors must ensure their contribution does not infringe on the +copyright of others and reference the copyright holder and license of +code parts under a compatible open-source license. We reserve the right +to reject any contributions where the copyright is in question. + Any new files contributed to the project should clearly state their intentions regarding copyright, in one of the following ways: @@ -177,6 +182,58 @@ intentions regarding copyright, in one of the following ways: __ ../../licenses/BSD-2-Clause.rst +AI Policy +========= + +All contributors must disclose whether AI [#ai]_ has been used to assist in +the development of their contributions. If so, they must document which +tool(s) have been used, how they were used, and specify what code or text +is AI generated. +We will reject contributions without accompanying AI disclosure. + +The use of an AI agent that writes code and then submits a patch +autonomously is not permitted. A human must check any generated code and +submit the patch. Please do not waste developers' time by submitting +code that is fully or mostly generated by AI and doesn't meet our +standards. + +Contributors are responsible for any code they submit for inclusion +in Docutils, regardless of whether it was manually written or generated +by AI. They must understand and be able to explain the submitted code as +well as the existing related code. It is not acceptable to submit a patch +that is not understood or cannot be explained by the submitter. +When documenting the contribution, do not use AI to automatically generate +comments or issue descriptions or update the user documentation. + +.. sidebar:: Further Reading + + - `Sphinx AI policy + <https://www.sphinx-doc.org/en/master/internals/ai-policy.html>`_ + - `LLVM AI tool policy <https://llvm.org/docs/AIToolPolicy.html>`_ + - `Open source AI contribution policies + <https://github.com/melissawm/open-source-ai-contribution-policies>`_ + - `Scientific Python community considerations around AI + <https://blog.scientific-python.org/scientific-python/ + community-considerations-around-ai/>`_ + - `Python developer's guide to AI tools + <https://devguide.python.org/getting-started/ai-tools/index.html>`_ + +When interacting with the maintainers (forums, discussions, issues, etc.) +do not use AI to speak for you, except for translation or grammar +editing. If the developers want to chat with a chatbot, they can do so +themselves. Human-to-human communication is essential for an open source +community to thrive. + +We thank the SymPy developers, whose `AI Generated Code and Communication +Policy`__ this section was adapted from. + +.. [#ai] "AI" herein refers to generative AI tools like large language + models (LLMs) that can generate, edit, and review software code, + images, or texts. + +__ https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html + + .. _Subversion Repository: Repository ~~~ --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-09-26 10:56:22
|
- Description has changed: Diff: ~~~~ --- old +++ new @@ -1,4 +1,82 @@ -I suggest to add the following paragraph about copyright responsibilities and section about use of AI for contributions to Docutils to the "Docutils Project Policies": +I suggest to add the following paragraph about copyright responsibilities and section about use of AI for contributions to Docutils to the "Docutils Project Policies". + +It is an adapted and shortened version of the Sphinx AI policy which itself is based on the AI policy of NumPy and SciPy which are based on SymPy's [AI Generated Code and Communication ++Policy](https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html). + +--- a/docutils/docs/dev/policies.rst ++++ b/docutils/docs/dev/policies.rst +@@ -153,6 +153,11 @@ the project for inclusion (via Subversion, SourceForge trackers, + mailing lists, or private email) are assumed to be in the public + domain as well. + ++Contributors must ensure their contribution does not infringe on the ++copyright of others and reference the copyright holder and license of ++code parts under a compatible open-source license. We reserve the right ++to reject any contributions where the copyright is in question. ++ + Any new files contributed to the project should clearly state their + intentions regarding copyright, in one of the following ways: + +@@ -177,6 +182,58 @@ intentions regarding copyright, in one of the following ways: + __ ../../licenses/BSD-2-Clause.rst + + ++AI Policy ++========= ++ ++All contributors must disclose whether AI [#ai]_ has been used to assist in ++the development of their contributions. If so, they must document which ++tool(s) have been used, how they were used, and specify what code or text ++is AI generated. ++We will reject contributions without accompanying AI disclosure. ++ ++The use of an AI agent that writes code and then submits a patch ++autonomously is not permitted. A human must check any generated code and ++submit the patch. Please do not waste developers' time by submitting ++code that is fully or mostly generated by AI and doesn't meet our ++standards. ++ ++Contributors are responsible for any code they submit for inclusion ++in Docutils, regardless of whether it was manually written or generated ++by AI. They must understand and be able to explain the submitted code as ++well as the existing related code. It is not acceptable to submit a patch ++that is not understood or cannot be explained by the submitter. ++When documenting the contribution, do not use AI to automatically generate ++comments or issue descriptions or update the user documentation. ++ ++.. sidebar:: Further Reading ++ ++ - `Sphinx AI policy ++ <https://www.sphinx-doc.org/en/master/internals/ai-policy.html>`_ ++ - `LLVM AI tool policy <https://llvm.org/docs/AIToolPolicy.html>`_ ++ - `Open source AI contribution policies ++ <https://github.com/melissawm/open-source-ai-contribution-policies>`_ ++ - `Scientific Python community considerations around AI ++ <https://blog.scientific-python.org/scientific-python/ ++ community-considerations-around-ai/>`_ ++ - `Python developer's guide to AI tools ++ <https://devguide.python.org/getting-started/ai-tools/index.html>`_ ++ ++When interacting with the maintainers (forums, discussions, issues, etc.) ++do not use AI to speak for you, except for translation or grammar ++editing. If the developers want to chat with a chatbot, they can do so ++themselves. Human-to-human communication is essential for an open source ++community to thrive. ++ ++We thank the SymPy developers, whose `AI Generated Code and Communication ++Policy`__ this section was adapted from. ++ ++.. [#ai] "AI" herein refers to generative AI tools like large language ++ models (LLMs) that can generate, edit, and review software code, ++ images, or texts. ++ ++__ https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html ++ ++ + .. _Subversion Repository: + + Repository + ~~~ diff --- a/docutils/docs/dev/policies.rst +++ b/docutils/docs/dev/policies.rst ~~~~ --- **[patches:#217] AI policy** **Status:** open **Group:** None **Created:** Sat Sep 26, 2026 10:51 AM UTC by Günter Milde **Last Updated:** Sat Sep 26, 2026 10:51 AM UTC **Owner:** nobody I suggest to add the following paragraph about copyright responsibilities and section about use of AI for contributions to Docutils to the "Docutils Project Policies". It is an adapted and shortened version of the Sphinx AI policy which itself is based on the AI policy of NumPy and SciPy which are based on SymPy's [AI Generated Code and Communication +Policy](https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html). --- a/docutils/docs/dev/policies.rst +++ b/docutils/docs/dev/policies.rst @@ -153,6 +153,11 @@ the project for inclusion (via Subversion, SourceForge trackers, mailing lists, or private email) are assumed to be in the public domain as well. +Contributors must ensure their contribution does not infringe on the +copyright of others and reference the copyright holder and license of +code parts under a compatible open-source license. We reserve the right +to reject any contributions where the copyright is in question. + Any new files contributed to the project should clearly state their intentions regarding copyright, in one of the following ways: @@ -177,6 +182,58 @@ intentions regarding copyright, in one of the following ways: __ ../../licenses/BSD-2-Clause.rst +AI Policy +========= + +All contributors must disclose whether AI [#ai]_ has been used to assist in +the development of their contributions. If so, they must document which +tool(s) have been used, how they were used, and specify what code or text +is AI generated. +We will reject contributions without accompanying AI disclosure. + +The use of an AI agent that writes code and then submits a patch +autonomously is not permitted. A human must check any generated code and +submit the patch. Please do not waste developers' time by submitting +code that is fully or mostly generated by AI and doesn't meet our +standards. + +Contributors are responsible for any code they submit for inclusion +in Docutils, regardless of whether it was manually written or generated +by AI. They must understand and be able to explain the submitted code as +well as the existing related code. It is not acceptable to submit a patch +that is not understood or cannot be explained by the submitter. +When documenting the contribution, do not use AI to automatically generate +comments or issue descriptions or update the user documentation. + +.. sidebar:: Further Reading + + - `Sphinx AI policy + <https://www.sphinx-doc.org/en/master/internals/ai-policy.html>`_ + - `LLVM AI tool policy <https://llvm.org/docs/AIToolPolicy.html>`_ + - `Open source AI contribution policies + <https://github.com/melissawm/open-source-ai-contribution-policies>`_ + - `Scientific Python community considerations around AI + <https://blog.scientific-python.org/scientific-python/ + community-considerations-around-ai/>`_ + - `Python developer's guide to AI tools + <https://devguide.python.org/getting-started/ai-tools/index.html>`_ + +When interacting with the maintainers (forums, discussions, issues, etc.) +do not use AI to speak for you, except for translation or grammar +editing. If the developers want to chat with a chatbot, they can do so +themselves. Human-to-human communication is essential for an open source +community to thrive. + +We thank the SymPy developers, whose `AI Generated Code and Communication +Policy`__ this section was adapted from. + +.. [#ai] "AI" herein refers to generative AI tools like large language + models (LLMs) that can generate, edit, and review software code, + images, or texts. + +__ https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html + + .. _Subversion Repository: Repository ~~~ diff --- a/docutils/docs/dev/policies.rst +++ b/docutils/docs/dev/policies.rst @@ -153,6 +153,11 @@ the project for inclusion (via Subversion, SourceForge trackers, mailing lists, or private email) are assumed to be in the public domain as well. +Contributors must ensure their contribution does not infringe on the +copyright of others and reference the copyright holder and license of +code parts under a compatible open-source license. We reserve the right +to reject any contributions where the copyright is in question. + Any new files contributed to the project should clearly state their intentions regarding copyright, in one of the following ways: @@ -177,6 +182,58 @@ intentions regarding copyright, in one of the following ways: __ ../../licenses/BSD-2-Clause.rst +AI Policy +========= + +All contributors must disclose whether AI [#ai]_ has been used to assist in +the development of their contributions. If so, they must document which +tool(s) have been used, how they were used, and specify what code or text +is AI generated. +We will reject contributions without accompanying AI disclosure. + +The use of an AI agent that writes code and then submits a patch +autonomously is not permitted. A human must check any generated code and +submit the patch. Please do not waste developers' time by submitting +code that is fully or mostly generated by AI and doesn't meet our +standards. + +Contributors are responsible for any code they submit for inclusion +in Docutils, regardless of whether it was manually written or generated +by AI. They must understand and be able to explain the submitted code as +well as the existing related code. It is not acceptable to submit a patch +that is not understood or cannot be explained by the submitter. +When documenting the contribution, do not use AI to automatically generate +comments or issue descriptions or update the user documentation. + +.. sidebar:: Further Reading + + - `Sphinx AI policy + <https://www.sphinx-doc.org/en/master/internals/ai-policy.html>`_ + - `LLVM AI tool policy <https://llvm.org/docs/AIToolPolicy.html>`_ + - `Open source AI contribution policies + <https://github.com/melissawm/open-source-ai-contribution-policies>`_ + - `Scientific Python community considerations around AI + <https://blog.scientific-python.org/scientific-python/ + community-considerations-around-ai/>`_ + - `Python developer's guide to AI tools + <https://devguide.python.org/getting-started/ai-tools/index.html>`_ + +When interacting with the maintainers (forums, discussions, issues, etc.) +do not use AI to speak for you, except for translation or grammar +editing. If the developers want to chat with a chatbot, they can do so +themselves. Human-to-human communication is essential for an open source +community to thrive. + +We thank the SymPy developers, whose `AI Generated Code and Communication +Policy`__ this section was adapted from. + +.. [#ai] "AI" herein refers to generative AI tools like large language + models (LLMs) that can generate, edit, and review software code, + images, or texts. + +__ https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html + + .. _Subversion Repository: Repository ~~~ --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-09-26 10:51:34
|
--- **[patches:#217] AI policy** **Status:** open **Group:** None **Created:** Sat Sep 26, 2026 10:51 AM UTC by Günter Milde **Last Updated:** Sat Sep 26, 2026 10:51 AM UTC **Owner:** nobody I suggest to add the following paragraph about copyright responsibilities and section about use of AI for contributions to Docutils to the "Docutils Project Policies": ~~~ diff --- a/docutils/docs/dev/policies.rst +++ b/docutils/docs/dev/policies.rst @@ -153,6 +153,11 @@ the project for inclusion (via Subversion, SourceForge trackers, mailing lists, or private email) are assumed to be in the public domain as well. +Contributors must ensure their contribution does not infringe on the +copyright of others and reference the copyright holder and license of +code parts under a compatible open-source license. We reserve the right +to reject any contributions where the copyright is in question. + Any new files contributed to the project should clearly state their intentions regarding copyright, in one of the following ways: @@ -177,6 +182,58 @@ intentions regarding copyright, in one of the following ways: __ ../../licenses/BSD-2-Clause.rst +AI Policy +========= + +All contributors must disclose whether AI [#ai]_ has been used to assist in +the development of their contributions. If so, they must document which +tool(s) have been used, how they were used, and specify what code or text +is AI generated. +We will reject contributions without accompanying AI disclosure. + +The use of an AI agent that writes code and then submits a patch +autonomously is not permitted. A human must check any generated code and +submit the patch. Please do not waste developers' time by submitting +code that is fully or mostly generated by AI and doesn't meet our +standards. + +Contributors are responsible for any code they submit for inclusion +in Docutils, regardless of whether it was manually written or generated +by AI. They must understand and be able to explain the submitted code as +well as the existing related code. It is not acceptable to submit a patch +that is not understood or cannot be explained by the submitter. +When documenting the contribution, do not use AI to automatically generate +comments or issue descriptions or update the user documentation. + +.. sidebar:: Further Reading + + - `Sphinx AI policy + <https://www.sphinx-doc.org/en/master/internals/ai-policy.html>`_ + - `LLVM AI tool policy <https://llvm.org/docs/AIToolPolicy.html>`_ + - `Open source AI contribution policies + <https://github.com/melissawm/open-source-ai-contribution-policies>`_ + - `Scientific Python community considerations around AI + <https://blog.scientific-python.org/scientific-python/ + community-considerations-around-ai/>`_ + - `Python developer's guide to AI tools + <https://devguide.python.org/getting-started/ai-tools/index.html>`_ + +When interacting with the maintainers (forums, discussions, issues, etc.) +do not use AI to speak for you, except for translation or grammar +editing. If the developers want to chat with a chatbot, they can do so +themselves. Human-to-human communication is essential for an open source +community to thrive. + +We thank the SymPy developers, whose `AI Generated Code and Communication +Policy`__ this section was adapted from. + +.. [#ai] "AI" herein refers to generative AI tools like large language + models (LLMs) that can generate, edit, and review software code, + images, or texts. + +__ https://docs.sympy.org/dev/contributing/ai-generated-code-policy.html + + .. _Subversion Repository: Repository ~~~ --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Dmitry S. <man...@us...> - 2026-09-24 20:14:37
|
Thank you! --- **[patches:#132] Add SOURCE\_DATE\_EPOCH support to date directive** **Status:** open-fixed **Group:** None **Created:** Sun Jul 24, 2016 05:49 PM UTC by Dmitry Shachnev **Last Updated:** Thu Sep 24, 2026 07:51 PM UTC **Owner:** nobody **Attachments:** - [0001-Add-SOURCE\_DATE\_EPOCH-support-to-the-date-directive.patch](https://sourceforge.net/p/docutils/patches/132/attachment/0001-Add-SOURCE_DATE_EPOCH-support-to-the-date-directive.patch) (1.1 kB; text/x-diff) Recently, a number of projects [joined efforts](https://reproducible-builds.org/) to make the builds of their software reproducible. One of the goals of this effort is getting rid of timestamps in generated files, such as the documentation and man pages. For this purpose, [a specification of `SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/) environment variable was developed, which various build systems can set and various projects can read. The attached patch (initially submitted by Chris Lamb to [Debian #831779](https://bugs.debian.org/831779)) adds support for that environment variable to docutils `date` directive. --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-09-24 19:58:13
|
- **status**: pending-moreinfo --> closed-wont-fix - **Comment**: Thank you for your suggestion and patch. However, I prefer not to change the DocumentTree definition and add one more configuration setting for a rare use case. Styling can and should preferabely be done with CSS stylesheets or LaTeX packages. --- **[patches:#179] Add option to place captions above figure** **Status:** closed-wont-fix **Group:** None **Created:** Mon Jan 18, 2021 07:35 PM UTC by Jesse Tan **Last Updated:** Sun Nov 10, 2024 10:02 PM UTC **Owner:** nobody **Attachments:** - [figure-caption-top.patch](https://sourceforge.net/p/docutils/patches/179/attachment/figure-caption-top.patch) (2.0 kB; application/octet-stream) Figures currently have a caption below the figure. This patch adds a config option that allows placement above the figure. Documentation is added, but no test. Tips on how to progress would be appreciated. --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-09-24 19:51:00
|
- **status**: pending-remind --> open-fixed - **Comment**: Support for SOURCE_DATE_EPOCH was added in [r10402]. --- **[patches:#132] Add SOURCE\_DATE\_EPOCH support to date directive** **Status:** open-fixed **Group:** None **Created:** Sun Jul 24, 2016 05:49 PM UTC by Dmitry Shachnev **Last Updated:** Thu Apr 17, 2025 12:07 PM UTC **Owner:** nobody **Attachments:** - [0001-Add-SOURCE\_DATE\_EPOCH-support-to-the-date-directive.patch](https://sourceforge.net/p/docutils/patches/132/attachment/0001-Add-SOURCE_DATE_EPOCH-support-to-the-date-directive.patch) (1.1 kB; text/x-diff) Recently, a number of projects [joined efforts](https://reproducible-builds.org/) to make the builds of their software reproducible. One of the goals of this effort is getting rid of timestamps in generated files, such as the documentation and man pages. For this purpose, [a specification of `SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/) environment variable was developed, which various build systems can set and various projects can read. The attached patch (initially submitted by Chris Lamb to [Debian #831779](https://bugs.debian.org/831779)) adds support for that environment variable to docutils `date` directive. --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-09-02 15:48:12
|
- **status**: open --> open-fixed - **Comment**: The issue should be fixed in [r10398]. Thank you for the report. --- **[bugs:#522] \`languages.get\_language\(\)\` unsafe fallback import lets PyPI package shadow language module \(e.g. \`id\`\)** **Status:** open-fixed **Created:** Mon Aug 31, 2026 03:59 PM UTC by Bart van der Braak **Last Updated:** Mon Aug 31, 2026 04:00 PM UTC **Owner:** nobody I'm DevOps Engineer at Blender and we noticed an issue popping up while building our the Indonesian language version of our documentation after updating one of our dependencies: ``` [32mpipenv run sphinx-build -b html -j 12 -D language=id ./manual /home/blender/git/blender-manual-v450/build/html/id[0m Courtesy Notice: Pipenv found itself running within a virtual environment, so it will automatically use that environment, instead of creating its own for any project. You can set PIPENV_IGNORE_VIRTUALENVS=1 to force pipenv to ignore that environment and create its own instead. You can set PIPENV_VERBOSITY=-1 to suppress this warning. Running Sphinx v7.4.7 loading translations [id]... done making output directory... done loading intersphinx inventory 'blender_api' from https://docs.blender.org/api/4.5/objects.inv... building [mo]: targets for 0 po files that are out of date writing output... building [html]: targets for 2072 source files that are out of date updating environment: [new config] 2072 added, 0 changed, 0 removed Sphinx parallel build error: AttributeError: module 'id' has no attribute 'bibliographic_fields' ``` Source: https://builder.staging.blender.org/admin/#/builders/16/builds/4 It looks like `docutils.languages.get_language()` falls back to a bare `import <language_code>` when no `docutils.languages.<code>` module exists. If a PyPI package happens to share the name of a language code (e.g. `id`, the PEP 740 attestations package used by `twine`), that package gets imported instead, breaking language support with no clear error. ### Reproduce I crafted the following A/B scenario: #### A: clean venv, no `id` package ```bash [bart@ws-bart:/tmp]$ python3 -m venv /tmp/env_clean [bart@ws-bart:/tmp]$ /tmp/env_clean/bin/pip install -q docutils [notice] A new release of pip is available: 26.1.2 -> 26.2.1 [notice] To update, run: /tmp/env_clean/bin/python3 -m pip install --upgrade pip [bart@ws-bart:/tmp]$ /tmp/env_clean/bin/python -c " from docutils.languages import get_language mod = get_language('id') print(mod) print(hasattr(mod, 'bibliographic_fields')) " <module 'docutils.languages.en' from '/tmp/env_clean/lib/python3.14/site-packages/docutils/languages/en.py'> True ``` #### B: venv with `id` pypi package installed ```bash [bart@ws-bart:/tmp]$ # --- B: venv with `id` pypi package installed --- [bart@ws-bart:/tmp]$ python3 -m venv /tmp/env_poisoned [bart@ws-bart:/tmp]$ /tmp/env_poisoned/bin/pip install -q docutils id [notice] A new release of pip is available: 26.1.2 -> 26.2.1 [notice] To update, run: /tmp/env_poisoned/bin/python3 -m pip install --upgrade pip [bart@ws-bart:/tmp]$ /tmp/env_poisoned/bin/python -c " from docutils.languages import get_language mod = get_language('id') print(mod) print(hasattr(mod, 'bibliographic_fields')) " <module 'id' from '/tmp/env_poisoned/lib/python3.14/site-packages/id/__init__.py'> False ``` ### Versions used ``` docutils 0.21.2, Python 3.12 ``` --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-08-25 19:53:58
|
Thanks for the report.
IMO, the issue is "SmartQuotes misclassifies an opening quote before non-ASCII punctuation when there are bracktes around".
Test sample:
~~~rst
The misclassification happens also in other cases:
('...') ("...") ('--') ("--") ('---') ("---") ASCII patterns
('…') ("…") ('–') ("–") ('—') ("—") ("—") Unicode punctuation
* No difference between single and double quotes
* No difference between smartquote patterns or direct Unicode input.
Word characters:
('a') ('b') ('c') ('D') ASCII
('ä') ('Ö') ('ß') ('λ') non-ASCII
ASCII punctuation and non-word characters:
('!') ('?') (';') (':') ('.') (',') ('/') ('#') ('+') ('-') ('*') ('=')
('^') ('"') ('%') ('$') but ('&')
non-ASCII punctuation:
('¡') ('¿') ('‧') ('‰') ('⁋') ('∀')
* ASCII punctuation (except the ampersand) is OK,
non-ASCII punctuation is problematic.
OTOH, without brackets, everything is fine:
'.' '&' '...' '--' '¡' '¿' '‧' '‰' '⁋'.
There are other misclassifications, e.g., the quote after an EM-DASH at the
end of a paragraph:
ASCII pattern ('---') ('---')
Unicode ('—') ('—')
~~~
> I'm not sure if this is an issue worth fixing, [...]
Nor am I, "smartquotes" is intended as a simple helper and will always have its limitations (cf. [caveats](https://docutils.sourceforge.io/docs/user/smartquotes.html#caveats)).
---
**[bugs:#520] SmartQuotes misclassifies an opening single quote before a converted ellipsis**
**Status:** open
**Created:** Thu Aug 20, 2026 10:33 PM UTC by Jared Dillard
**Last Updated:** Thu Aug 20, 2026 10:33 PM UTC
**Owner:** nobody
When smart quotes and ellipsis conversion are enabled, a straight single quote before `...` is converted to a closing quotation mark instead of an opening quotation mark.
Input:
```text
Add secondary prompts ('...') to the sidebar.
```
Actual output:
```text
Add secondary prompts (’…’) to the sidebar.
```
Expected output:
```text
Add secondary prompts (‘…’) to the sidebar.
```
In the actual output, both quotes are U+2019 RIGHT SINGLE QUOTATION MARK. The opening quote should be U+2018 LEFT SINGLE QUOTATION MARK.
## Minimal reproduction
```python
from docutils.core import publish_parts
source = "Add secondary prompts ('...') to the sidebar.\n"
parts = publish_parts(
source,
writer_name="html5",
settings_overrides={
"smart_quotes": True,
"language_code": "en",
},
)
print(parts["fragment"].strip())
```
Output:
```html
<p>Add secondary prompts (’…’) to the sidebar.</p>
```
## Environment
- Python: 3.12.7
- Docutils: 0.22.3
## Additional context
This was originally reported in [Sphinx issue #9713](https://github.com/sphinx-doc/sphinx/issues/9713). Docutils 0.17 fixed the separate quote-classification cases involving opening or separator characters such as `[`, `-`, and `+`. Those cases work with Docutils 0.22.3, but the ellipsis case above remains reproducible. I'm not sure if this is an issue worth fixing, but wanted to pass it along.
The behavior seems to be related to conversion order: `...` becomes U+2026 HORIZONTAL ELLIPSIS before the neighboring quote is classified.
---
Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/
To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-08-22 21:08:56
|
- **status**: open --> open-fixed - **Comment**: Fixed in [r10395]. --- **[bugs:#521] Document fetch triggered by XML writer raw XML validation** **Status:** open-fixed **Created:** Fri Aug 21, 2026 12:21 PM UTC by Florian Weimer **Last Updated:** Fri Aug 21, 2026 12:21 PM UTC **Owner:** nobody **Attachments:** - [RHEL-214776.html](https://sourceforge.net/p/docutils/bugs/521/attachment/RHEL-214776.html) (7.8 kB; text/html) Red Hat Product Security has asked me to forward the attached vulnerability report. I do not think it is a significant issue (perhaps no vulnerability at all), so I'm not filing a private bug for it. This is a small reproducer: ``` from docutils.core import publish_string RST_INPUT = """\ .. raw:: xml <!DOCTYPE r [<!ENTITY xxe SYSTEM "http://127.0.0.1:9/">]> <r>&xxe;</r> """ print(publish_string(RST_INPUT, writer_name='xml')) ``` It fails with a `urllib.error.URLError` exception, indicating that the conversion triggered unexpected network activity. I've been told to mention: Found by AISLE in partnership with Red Hat --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2026-08-21 13:57:41
|
- **status**: open --> open-fixed - **private**: Yes --> No - **Comment**: The issue is fixed in [r10394]. Thank you again for reporting. --- **[bugs:#519] XSS via unescaped HTML in PEP email masking transform** **Status:** open-fixed **Created:** Mon Jul 27, 2026 10:09 AM UTC by Florian Weimer **Last Updated:** Sat Aug 15, 2026 07:10 PM UTC **Owner:** nobody **Attachments:** - [RHEL-214726.txt](https://sourceforge.net/p/docutils/bugs/519/attachment/RHEL-214726.txt) (5.9 kB; text/plain) I have been instructed to forward the attached security report to you privately. As far as I can tell, it is accurate, and the vulnerability is still present in the current sources. My understanding is that docutils offers a processing mode that is robust in the presence of malicious inputs, which is why a trust boundary is crossed. Please let me know how you want to handle this. An automatically generated proper reproducer looks like this: ``` #!/usr/bin/env python3 """Reproducer for XSS in PEP email masking transform (mask_email).""" import sys sys.path.insert(0, 'docutils') from docutils.core import publish_parts src = """\ PEP: 9999 Title: Test Author: `"><img src=x onerror=alert(1)> <ev...@ex...>`_ Status: Draft Type: Standards Track Created: 01-Jan-2026 Abstract ======== Test. """ parts = publish_parts(source=src, reader_name='pep', writer_name='html') body = parts['html_body'] if '<img src=x onerror=alert(1)>' in body: print('VULNERABLE: unescaped HTML found in output') print() for line in body.splitlines(): if 'onerror' in line: print(' ', line.strip()) sys.exit(1) else: print('OK: no unescaped HTML in output') sys.exit(0) ``` The reconstructed patch is: ``` Index: docutils/docutils/transforms/peps.py =================================================================== --- docutils/docutils/transforms/peps.py (revision 10391) +++ docutils/docutils/transforms/peps.py (working copy) @@ -303,8 +303,8 @@ if ref['refuri'][8:] in non_masked_addresses: replacement = ref[0] else: - replacement_text = ref.astext().replace('@', ' at ') - replacement = nodes.raw('', replacement_text, format='html') + replacement_text = ref.astext().replace('@', ' at ') + replacement = nodes.Text(replacement_text) if pepno is None: return replacement else: ``` --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Guenter M. <mi...@us...> - 2026-08-15 11:34:19
|
Dear Florian, On 2026-07-27, Florian Weimer via Docutils-develop wrote: > I've noticed that private bugs are announced on this list, making the > private checkbox in the Sourceforge bug tracker ineffictive. Thank you for pointing this out. Sorry for the delay, I was on summer holidays in the great outdoors. I changed the settings to "Send notifications for: All public ticket changes", so this should no longer be an issue. Instead, there is a real chance that the issue is overlooked as I usually just check the lists. > Is there are more reliable way to report security > issues privately? You can email the developers directly, preferably the one(s) listed in copyright notice of the affected module file (however, some developers are no longer active). That said, I was able to read your private bug report and will respond there. Günter |
|
From: Florian W. <fw...@re...> - 2026-07-27 12:08:16
|
I've noticed that private bugs are announced on this list, making the private checkbox in the Sourceforge bug tracker ineffictive. I think I successfully canceled the previous attempt to post a private bug of mine here. Is there are more reliable way to report security issues privately? (The issues I've been asked to report probably do not need to handled privately in my personal opinion, but I've been specifically instructed not to report them publicly, and would have to obtain permission from our security team before posting them to this list, for example.) Thanks, Florian |
|
From: engelbert g. <eng...@gm...> - 2026-06-11 13:58:10
|
Yes +2 for this personally i tried ai and indeed not fit my work ... way as long as we are not on any git pull requests mean commits, patches, contributions i somehow think restricting to git-language a little bit limited cheers On Wed, 10 Jun 2026 at 19:03, Karl O. Pinc <ko...@ka...> wrote: > > On 2026-06-10 11:02, Guenter Milde via Docutils-develop wrote: > > > our sister (or daughter) project Sphinx just added an AI policy page > > https://www.sphinx-doc.org/en/master/internals/ai-policy.html > > > > I propose to include a similar text into our Project Policies > > https://docutils.sourceforge.io/docs/dev/policies.html > > > > What do you think? > > Makes perfect sense to me. But that means pretty much > nothing because I have no real standing regards > docutils. > > > _______________________________________________ > Docutils-develop mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-develop > > Please use "Reply All" to reply to the list. |
|
From: Günter M. <mi...@us...> - 2026-06-11 08:29:27
|
- **status**: pending --> open-fixed - **Comment**: The second positional argument for the destination is dropped in [r10348] . Now, more than one positional argument will result in an error. Use the `--output` and `-o` options or output redirection (`>`) to specify an output file. --- **[feature-requests:#36] prevent accidential file overwrites by wildcard expansion** **Status:** open-fixed **Group:** Default **Created:** Fri Mar 15, 2013 10:43 PM UTC by Jakub Wilk **Last Updated:** Tue Apr 29, 2025 07:47 PM UTC **Owner:** nobody A Debian user complained that if you use a wildcard as input file name, and the wildcard unexpectedly expands to two names, then rst2html will overwrite your files: http://bugs.debian.org/654690 Would if be possible to add an option for not overwriting output files, that you could add to your configuration file, and later override from command line if needed? --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: engelbert g. <eng...@gm...> - 2026-06-10 20:12:20
|
i am fine with 1.0 cheers On Wed, 10 Jun 2026 at 11:27, Guenter Milde via Docutils-develop <doc...@li...> wrote: > > Dear Docutils develpers, > > it is now 2 weeks since > On 2026-05-27, engelbert gruber wrote: > > > release 0.23 is out > > > There has been no doc report yet, so either there are no new bugs :) > or no one cares. :( > > I suggest to let the next release be Docutils 1.0. > This allows us to officially switch to `Semantic Versioning`__ > and to implement the changes__ anounced for 1.0. > > __ https://semver.org/ > __ https://docutils.sourceforge.io/RELEASE-NOTES.html#future-changes > > Thanks, > Günter > > > > _______________________________________________ > Docutils-develop mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-develop > > Please use "Reply All" to reply to the list. |
|
From: Karl O. P. <ko...@ka...> - 2026-06-10 17:03:16
|
On 2026-06-10 11:02, Guenter Milde via Docutils-develop wrote: > our sister (or daughter) project Sphinx just added an AI policy page > https://www.sphinx-doc.org/en/master/internals/ai-policy.html > > I propose to include a similar text into our Project Policies > https://docutils.sourceforge.io/docs/dev/policies.html > > What do you think? Makes perfect sense to me. But that means pretty much nothing because I have no real standing regards docutils. |
|
From: Guenter M. <mi...@us...> - 2026-06-10 16:02:22
|
Dear Docutils developers, our sister (or daughter) project Sphinx just added an AI policy page https://www.sphinx-doc.org/en/master/internals/ai-policy.html I propose to include a similar text into our Project Policies https://docutils.sourceforge.io/docs/dev/policies.html What do you think? Günter |
|
From: Guenter M. <mi...@us...> - 2026-06-10 09:26:59
|
Dear Docutils develpers, it is now 2 weeks since On 2026-05-27, engelbert gruber wrote: > release 0.23 is out There has been no doc report yet, so either there are no new bugs :) or no one cares. :( I suggest to let the next release be Docutils 1.0. This allows us to officially switch to `Semantic Versioning`__ and to implement the changes__ anounced for 1.0. __ https://semver.org/ __ https://docutils.sourceforge.io/RELEASE-NOTES.html#future-changes Thanks, Günter |