docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:patches] #192 Codebase modernisation

[Adam T. <aa-...@us...>]

Thanks! I really appreciate it.

> error catching: here we should check for the most appropriate (sub)class to use,

OK. Python 3 did change IO and Environment errors to be identical to OSError -- but as you say the exception hierarchy was reworked so e.g. FileNotFoundError or whatever may be more appropriate.

> the recommonmark test 

As currently it is just a no-op statement. (I don't have recommonmark set up for docutils on my laptop, which is probably why I missed that tests fail -- sorry!) Perhaps just remove?

>  some set/dict literals where the "tratidional" form seems more clear,

OK. For html4css1 Line 159, perhaps `special_characters = _html_base.HTMLTranslator.special_characters.copy()` if you don't like the `{**...}` form? It makes that the intention is to copy much clearer.

A



---

** [patches:#192] Codebase modernisation**

**Status:** open
**Group:** None
**Created:** Wed Jan 26, 2022 12:37 AM UTC by Adam  Turner
**Last Updated:** Wed Jan 26, 2022 10:35 PM UTC
**Owner:** nobody


This follows on from the Python 2.x cleanup work.

The total diff looks quite large, but the marjority of these are mechanical search / replace changes -- viewing by commit or in groups of commits may be best. 

https://github.com/AA-Turner/docutils/pull/12 // https://github.com/AA-Turner/docutils/pull/12.patch

I kept things seperate so that it would be easier to extract and rebase changes that you don't want to merge (hopefully there aren't any of these!).

A


---

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.

[Docutils-develop] [docutils:patches] #192 Codebase modernisation

[Günter M. <mi...@us...>]

Thank you for the patch set. I spent the day reviewing and implementing.
Not changed: 
* some set/dict literals where the "tratidional" form seems more clear,
* error catching: here we should check for the most appropriate (sub)class to use,
* deprecated and generated modules,
* assignments before return, when they improve code readability.
* the recommonmark test (works here as-is, fails with proposed changes) What recommonmark version do you use for the test? Which OS?




---

** [patches:#192] Codebase modernisation**

**Status:** open
**Group:** None
**Created:** Wed Jan 26, 2022 12:37 AM UTC by Adam  Turner
**Last Updated:** Wed Jan 26, 2022 12:37 AM UTC
**Owner:** nobody


This follows on from the Python 2.x cleanup work.

The total diff looks quite large, but the marjority of these are mechanical search / replace changes -- viewing by commit or in groups of commits may be best. 

https://github.com/AA-Turner/docutils/pull/12 // https://github.com/AA-Turner/docutils/pull/12.patch

I kept things seperate so that it would be easier to extract and rebase changes that you don't want to merge (hopefully there aren't any of these!).

A


---

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.

[Docutils-develop] [docutils:bugs] #443 html5 writer no longer honors "[html writers]" config section

[Günter M. <mi...@us...>]

- **status**: open --> open-fixed
- **Comment**:

Fixed in [r8967].
Thank you for reporting the bug.



---

** [bugs:#443] html5 writer no longer honors "[html writers]" config section**

**Status:** open-fixed
**Labels:** HTML writer 
**Created:** Tue Jan 25, 2022 07:51 PM UTC by John Thorvald Wodder II
**Last Updated:** Tue Jan 25, 2022 07:51 PM UTC
**Owner:** nobody


Under both version 0.18 and version 0.18.1 of Docutils, `rst2html5.py` does not recognize configuration settings in an `[html writers]` section in `docutils.conf`.  This appears to be due to commit 8722, in which `_html_base.py` was edited to no longer include `"html writers"` in its `config_section_dependencies`, instead moving the value to `config_section`; while `html4css1/__init__.py` was updated in the same commit to include `"html writers"` in its `config_section_dependencies`, `html5_polyglot/__init__.py` did not get the same treatment.


---

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.

[Docutils-develop] [docutils:patches] #192 Codebase modernisation

[Adam T. <aa-...@us...>]

---

** [patches:#192] Codebase modernisation**

**Status:** open
**Group:** None
**Created:** Wed Jan 26, 2022 12:37 AM UTC by Adam  Turner
**Last Updated:** Wed Jan 26, 2022 12:37 AM UTC
**Owner:** nobody


This follows on from the Python 2.x cleanup work.

The total diff looks quite large, but the marjority of these are mechanical search / replace changes -- viewing by commit or in groups of commits may be best. 

https://github.com/AA-Turner/docutils/pull/12 // https://github.com/AA-Turner/docutils/pull/12.patch

I kept things seperate so that it would be easier to extract and rebase changes that you don't want to merge (hopefully there aren't any of these!).

A


---

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.

[Docutils-develop] [docutils:bugs] #441 Move from "optparse" to "argparse".

[Adam T. <aa-...@us...>]

From FR# 88

> I am just working on a way to disentangle frontend.OptionParser and frontend.ConfigParser but this is a topic for bug:#441

Sounds good -- happy to review a proposed design. 

I'd propose making the `--config` flag simply store the path to the file, and then add it to the list of config files to be read.

`get_config_file_settings` should also probably be removed from `OptionParser` -- instead a dict should be returned by `ConfigParser` and merged in.

> I didn't go into detail intentionally so as not to spark a debate about these parts, but I do think (eventually) simplifying these interactions can lead to a cleaner codebase.


> Docutils has an elaborated configuration framework which actually predates the "optparse" module. Later development of "Optik" into "optparse" and then "argparse" implemented some of the abstractions and enhancements offered by Docutils in a different way.

Ideally, we would construct a single `ArgumentParser` object and add arguments "normally" through `parser.add_argument`. The problem here is that subclasses can filter settings_spec (through filter_settings_spec). 

I've never seen this implemented in the way Docutils does it before -- if settings_spec tuples were treated as immutable, then things would be much simpler. 

________

We could also move to a model (a la stdlib `dataclasses` where we simply specify the setting name, type and default within the Component itself. The front-end tools could then use that information (or a mapping of settings to command line options or similar) to create the CLI arguments. 

I think this would be cleanest, but this cannot be done overnight.

_____

Did you have a chance to review my comments above in the previous post? It would be good to get some of this merged, or know what is blocking it // needs changing.

A



---

** [bugs:#441] Move from "optparse" to "argparse".**

**Status:** open
**Created:** Thu Jan 06, 2022 03:02 PM UTC by Günter Milde
**Last Updated:** Thu Jan 20, 2022 02:57 AM UTC
**Owner:** Günter Milde


The optparse documentation says:
> Deprecated since version 3.2: The optparse module is deprecated and will not be developed further; development will continue with the argparse module.

We are currently suppressing related deprecation warnings in the test suite.
After raising the Python dependency to >=3.7, now may be the right time to make the move.


---

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.

[Docutils-develop] [docutils:bugs] #443 html5 writer no longer honors "[html writers]" config section

[John T. W. I. <jw...@us...>]

---

** [bugs:#443] html5 writer no longer honors "[html writers]" config section**

**Status:** open
**Labels:** HTML writer 
**Created:** Tue Jan 25, 2022 07:51 PM UTC by John Thorvald Wodder II
**Last Updated:** Tue Jan 25, 2022 07:51 PM UTC
**Owner:** nobody


Under both version 0.18 and version 0.18.1 of Docutils, `rst2html5.py` does not recognize configuration settings in an `[html writers]` section in `docutils.conf`.  This appears to be due to commit 8722, in which `_html_base.py` was edited to no longer include `"html writers"` in its `config_section_dependencies`, instead moving the value to `config_section`; while `html4css1/__init__.py` was updated in the same commit to include `"html writers"` in its `config_section_dependencies`, `html5_polyglot/__init__.py` did not get the same treatment.


---

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.

[Docutils-develop] [docutils:feature-requests] #89 Public API, versioning, and deprecation

[Günter M. <mi...@us...>]

Draft for a "Public API and Backwards Compatibility Policy" document.


Attachments:

- [backwards-compatibility.txt](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/c3485acc56/069f/attachment/backwards-compatibility.txt) (5.5 kB; text/plain)


---

** [feature-requests:#89] Public API, versioning, and deprecation**

**Status:** open
**Group:** Default
**Created:** Sun Jan 16, 2022 01:39 AM UTC by Adam  Turner
**Last Updated:** Mon Jan 24, 2022 10: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.

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.

[Docutils-develop] [docutils:feature-requests] Re: #88 Unify Docutils CLI tools into `docutils-cli`

[Adam T. <aa-...@us...>]

> Even with Sphinx, some features can only be customised from a
docutils.conf configuration file.

> The sttings_spec and document.settings are Docutils abstraction from
the different configuration ways (config-files/command line/programmatic).
Using document.settings should be possible without too much thinking
about the actual source of the setting value.

> An overview for programmatic use of the "settings" framework is given in
https://docutils.sourceforge.io/docs/api/runtime-settings.html#runtime-settings-processing-from-applications
(best read alongside pydoc3 -b output for the mentioned functions/classes).

Note I'm not proposing getting rid of the config, just loosening the direct relationship between the CLI-parsing part of Docutils and the settings/config part of Docutils. 

> We already have the docutils.core.publish_* "convenience functions" as
a high-level API for custom front-ends (both command-line and programmatic).

Hmm, perhaps we are talking at cross purposes. I'm talking about utility functions such as "take some RST and turn in into docutils nodes" (from halfway down https://github.com/sphinx-doc/sphinx/issues/8039, ignore the emotive language). 

What the user probably wanted is `docutils.core.publish_doctree(user_input_text).children`, but it is pretty hard to know this without knowing the internals of Docutils. A function named `get_nodes_from_rst` (or suchlike) would be a useful helper. 

There is currently a great degree of useage of random internal bits of Docutils, I think partially due to that these "medium level" helpers don't exist (sorry if I wasn't clear in what I meant here in the post above). 

> we want the components to be configurable from the command line or config file

I would challenge this, I would find this very surprising behaviour if a config file (in one of at least three places, or controlled by an environment file) populated defaults to the *components* being used. Given it also adds a lot of complexity, I'm not sure it is worth keeping?

>  implemented some of the abstractions and enhancements offered by Docutils in a different way.

The main challenge I had here was that subclasses can filter `settings_spec` (through `filter_settings_spec`). I've never seen this implemented in the way Docutils does it before -- if `settings_spec` tuples were treated as immutable, then it would be much easier to e.g. construct the parser object first and then use `parser.add_argument` as "intended". 

> simple front-ends in favour of one complex front end

I'll try another analogy (why not!) . When I'm using `ffmpeg`, it is "simple" to me as the end user to know that if I want to use different input or output encodings, I just pass the relevant flag. All I need to learn is the name of the base command, and that I pass the codec I want to `-c:a` and `-c:v`.  In this way it is "simpler" to remember and use as the number of commands goes up (and allows using aliases, which the per-format tools don't). 

The implementation might be somewhat more complex (although I would argue not much), but end-user simplicity is what counts.

If you're not conviced I'll drop the issue for now, I do think it would be good to at least unify the back-end implementations of the front-end tools.

> two packages at pypi

I don't think this is a good idea -- it increases confusion as there are two packages, but the "core" maintains all the complexity of needing to parse CLI stuff. Maybe later, if the core (or CLI) become more distinct.

> I propose to move it to docutils/writers/odtwriter/

+1

Will reply on 441 for the 441 things.

A





---

** [feature-requests:#88] Unify Docutils CLI tools into `docutils-cli`**

**Status:** open
**Group:** Default
**Created:** Sat Jan 15, 2022 10:11 PM UTC by Adam  Turner
**Last Updated:** Thu Jan 20, 2022 01:52 AM UTC
**Owner:** nobody


As noted at https://sourceforge.net/p/docutils/patches/186/?page=1#897a/547e/ef2d by @milde, 
> we should open a new ticket for the command line tool review

This is a tracker issue for this, and to allow discussion. 

I'll briefly re-outline my argument to (eventually) drop the `rst*` front-end tools, and only export `docutils-cli` (or `python -m docutils`). 

> I think a single front-end tool significantly simplifies a lot of things -- the docutils-cli wrapper is not complex, which gives it significant points in favour in my book.

> Most usage of Docutils today is programmatic, and not via the command line tools (see the table at the bottom of this post - it shows all the projects that have a full dependency on Docutils with over 500k downloads in the last month. Of those 8, none use the command line tools)

> I also suspect (although the data does not exist) that most command line uses of the Docutils tools will be rst2html(5). This is already the default in docutils-cli, so it is a drop-in replacement.

> ...

>  My proposal isn't to remove them *\[the rst2 front-end tools\]* with no recourse, but to deprecate over a period of time, clearly marking identical drop-in commands at runtime to affected users. ... We cannot know how many people would be affected with local random scripts, but it is a two-second change.

> Many users will also run with old or pinned versions of Docutils, and part of updating is seeing the changelog. If Debian or other redistributors already make changes, they could decide to keep shell aliases from rst2* to the new docutils-cli based invocations. 

(quotes taken from https://sourceforge.net/p/docutils/patches/186/#897a and https://sourceforge.net/p/docutils/patches/186/?page=1#897a/547e )

A


---

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.

[Docutils-develop] [docutils:feature-requests] Re: #89 Public API, versioning, and deprecation

[Adam T. <aa-...@us...>]

> > Consider introducing underscores for existing names, through `__getattr__` or similar (with full backwards compatability and a deprecation period, and ideally helper functions to mean that downstream users don't need to use internal things as much)

> I'd rather not.

Fair enough.

> I don't insist on type annotations as indicator. However, adding type annotations to existing code should concentrate on the public API.

This is good to hear, and I agree that to begin with we should concentrate on the public API.

> I'll attach an draft document that tries to sum up what we have reached so
far (work in progress).

Look forwards to it!

A


---

** [feature-requests:#89] Public API, versioning, and deprecation**

**Status:** open
**Group:** Default
**Created:** Sun Jan 16, 2022 01:39 AM UTC by Adam  Turner
**Last Updated:** Thu Jan 20, 2022 02:27 AM 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.

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.

Re: [Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[chris s. <chr...@ho...>]

Again you haven’t supplied any reference to support your claims.

> you have not given a single reason why not GitLab

You wouldn’t be able to have integrated referencing (in issues and PRs) between docutils and sphinx, readthedocs, myst, and the majority of the python ecosystem that are on GitHub. Also first-class integration with VS Code, the most used development tool,...

Anyhow I’m not going to continue a flame war. I just wanted to make sure that your views wasn’t the only one represented here.

Cheers,
Chris

On 23 Jan 2022, at 12:49, Jeffrey C. Jacobs <tim...@st...> wrote:




On Fri, Jan 21, 2022 at 02:39 Juan Luis Cano Rodríguez <jua...@re...<mailto:jua...@re...>> wrote:
GitHub is an American company, and GitLab is hosted on Google Cloud Platform, an American company, and SourceForge is owned by Slashdot Media, an American company. American companies are subject to American laws, in particular regarding trade restrictions and sanctions to other countries[1].

Nonetheless it is blocked by US companies and federal agencies and the reason stated is ties to China. I’m thinking fighting the US government on its opinions of this is a battle of logic you’re not going to win. GitHub is a barrier, GitLab is not. I vote GitLab.

Also, defending GitHub you have not given a single reason why not GitLab, so, if they are equivalent, they why not GitLab?

Personally, I don’t like leaving the office and reading GitHub on my phone just to do something.

Jeffrey
--
"Scan not a friend with a microscopic glass; you know his faults so let his foibles pass." -- Victorian Proverb, likely Sir Frank Crisp, 1st Baronet of Bungay

"Dans le silence on ne sait pas, il faut continuer, je ne peux pas continuer, je vais continuer." -- L'Innommable, Samuel Beckett

"and thus the whirligig of time brings in his revenges" -- The Clown
  from 'Twelfth Night' v, , Act 5, Scene 1 by William Shakespeare

"Le mieux est l'ennemi du bien." -- François-Marie Arouet (Voltare), La Bégueule (1772)

~,-;`    The TimeHorse

Re: [Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[Jeffrey C. J. <tim...@st...>]

On Fri, Jan 21, 2022 at 02:39 Juan Luis Cano Rodríguez <
jua...@re...> wrote:

> GitHub is an American company, and GitLab is hosted on Google Cloud
> Platform, an American company, and SourceForge is owned by Slashdot Media,
> an American company. American companies are subject to American laws, in
> particular regarding trade restrictions and sanctions to other countries[1].
>
> Nonetheless it is blocked by US companies and federal agencies and the
reason stated is ties to China. I’m thinking fighting the US government on
its opinions of this is a battle of logic you’re not going to win. GitHub
is a barrier, GitLab is not. I vote GitLab.

Also, defending GitHub you have not given a single reason why not GitLab,
so, if they are equivalent, they why not GitLab?

Personally, I don’t like leaving the office and reading GitHub on my phone
just to do something.

Jeffrey
-- 
"Scan not a friend with a microscopic glass; you know his faults so let his
foibles pass." -- Victorian Proverb, likely Sir Frank Crisp, 1st Baronet of
Bungay

"Dans le silence on ne sait pas, il faut continuer, je ne peux pas
continuer, je vais continuer." -- L'Innommable, Samuel Beckett

"and thus the whirligig of time brings in his revenges" -- The Clown
  from 'Twelfth Night' v, , Act 5, Scene 1 by William Shakespeare

"Le mieux est l'ennemi du bien." -- François-Marie Arouet (Voltare), La
Bégueule (1772)

~,-;`    The TimeHorse

[Docutils-develop] [docutils:feature-requests] Re: #88 Unify Docutils CLI tools into `docutils-cli`

[Günter M. <mi...@us...>]

> Currently deep in Docutils' internals (everywhere that takes a
> `settings_spec` or uses `self.settings` sort of assumes working as a
> command line programme. However, a lot of usage (programmatic, through
> Sphinx or other methods) entirely use the default values for things.

Even with Sphinx, some features can only be customised from a
docutils.conf configuration file.

The `sttings_spec` and `document.settings` are Docutils abstraction from
the different configuration ways (config-files/command line/programmatic).
Using `document.settings` should be possible without too much thinking
about the actual source of the setting value.

An overview for programmatic use of the "settings" framework is given in
https://docutils.sourceforge.io/docs/api/runtime-settings.html#runtime-settings-processing-from-applications
(best read alongside `pydoc3 -b` output for the mentioned functions/classes).

> By moving to a single front end I would argue it is not only a cleaner
> user story, but it *might* enable refactoring to move the CLI usages of
> Docutils to a higher level.

We already have the `docutils.core.publish_*` "convenience functions" as
a high-level API for custom front-ends (both command-line and programmatic).

"docutils-cli" is more complex because here we want the components to be
configurable from the command line or config file. I am working on moving
the complexity to a library function that can be re-used by other
"script" entry-points in need of configurable components. This will become
an extension or addition to `docutils.core.publish_cmdline()`.
(It may also become simpler once "optparse" is replaced with "argparse".)

> Currently we need to do awful things to subclass and patch either
> `optparse.OptionParser` or `argparse.ArgumentParser`. This is really
> unusual, and for developers coming from a more "normal" command line
> application, it can take a while to understand this part of the
> internals of Docutils.

Yes, indeed. Docutils has an elaborated configuration framework which
actually predates the "optparse" module. Later development of "Optik"
into "optparse" and then "argparse" implemented some of the abstractions and
enhancements offered by Docutils in a different way.

But (in contrast to developers working on the optparse->argparse
transition :) "normal" developers using the "docutils" package don't need
to care about the details here. They can use the high-level API offered
by SettingsSpec / settings and get the command line and config file
processing for free (`docutils.frontend` is only the "workhorse", 
`docutils.core` is the high-level interface).
I agree that there is room for improvement in this API, but I don't think
getting rid of the simple front-ends in favour of one complex front end
will be of much help in this quest.

> I didn't go into detail intentionally so as not to spark a debate about
> these parts, but I do think (eventually) simplifying these interactions
> can lead to a cleaner codebase.

I suggest moving this thread of the discussion over to [bug:#441].


>> the two-stage command line parsing

> I don't think you can get away from this though without a combinatorial
> explosion of readers, writers, and parsers.
> Say we have two useful CLI readers (standalone/pep), three parsers
> (rst/recommonmark/myst), and 6 useful writers
> (html5/html4/latex/xetex/man/xml) that is 36 distinct front-end tools
> we should be providing.

However, only some of the combinations will be of common interest.
We should try to find the right balance -- IMO, both extremes are
sub-optimal.

* Docutils will not include dedicated front-end tools for 3rd-party
  parsers/writers/... ("pycmark2..." shall be provided by "pycmark" etc).

* One idea is to have two packages at pypi: "docutils-core", say,
  without dedicated front-end tools (but supporting `python -m docutils`)
  and "docutils" providing a sensible set of front-end tools.

* Another idea is to auto-install a small default set (rst2html,
  rst2latex, ...) and keep a rich set in `/tools` so that every user may
  install (copy, symlink or write alias commands in ~/.bashrc or
  ~/.profile) the tools the want "by hand".

* `rst2odt_prepstyles.py` is a rarely used auxiliary script.
  I propose to move it to `docutils/writers/odtwriter/`
  (alongside the stylefile(s) it prepares).

...


>> Ease of discovery is important. TAB completion is a powerful means here

> Did you see my suggestion on using custom shell autocompletion
> functions? I believe that this would allow for tab completion with the
> reader/parser/writer flags.

That is a possibility. However, it only works with some shells (bash) so it
is not for all users.

>> rst2 is established as the start of Docutils' front-end names for
>> conversion from reStructuredText to something. I would like to keep
>> this prefix as "ours".

> If we use what I propsed in one of my changesets to reimplement the
> `rst2` commands in terms of `docutils-cli`, it would be entirely
> possible to deprecate the `rst2` commands but just keep them forever.
> This would also mean that the simplifications I proposed at the top of
> this message wouldn't be blocked (I think).

I am just working on a way to disentangle frontend.OptionParser and
frontend.ConfigParser but this is a topic for [bug:#441].


---

** [feature-requests:#88] Unify Docutils CLI tools into `docutils-cli`**

**Status:** open
**Group:** Default
**Created:** Sat Jan 15, 2022 10:11 PM UTC by Adam  Turner
**Last Updated:** Thu Jan 20, 2022 01:52 AM UTC
**Owner:** nobody


As noted at https://sourceforge.net/p/docutils/patches/186/?page=1#897a/547e/ef2d by @milde, 
> we should open a new ticket for the command line tool review

This is a tracker issue for this, and to allow discussion. 

I'll briefly re-outline my argument to (eventually) drop the `rst*` front-end tools, and only export `docutils-cli` (or `python -m docutils`). 

> I think a single front-end tool significantly simplifies a lot of things -- the docutils-cli wrapper is not complex, which gives it significant points in favour in my book.

> Most usage of Docutils today is programmatic, and not via the command line tools (see the table at the bottom of this post - it shows all the projects that have a full dependency on Docutils with over 500k downloads in the last month. Of those 8, none use the command line tools)

> I also suspect (although the data does not exist) that most command line uses of the Docutils tools will be rst2html(5). This is already the default in docutils-cli, so it is a drop-in replacement.

> ...

>  My proposal isn't to remove them *\[the rst2 front-end tools\]* with no recourse, but to deprecate over a period of time, clearly marking identical drop-in commands at runtime to affected users. ... We cannot know how many people would be affected with local random scripts, but it is a two-second change.

> Many users will also run with old or pinned versions of Docutils, and part of updating is seeing the changelog. If Debian or other redistributors already make changes, they could decide to keep shell aliases from rst2* to the new docutils-cli based invocations. 

(quotes taken from https://sourceforge.net/p/docutils/patches/186/#897a and https://sourceforge.net/p/docutils/patches/186/?page=1#897a/547e )

A


---

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.

Re: [Docutils-develop] [docutils:patches] Re: #191 Update URLs

[Guenter M. <mi...@us...>]

On 2022-01-21, Adam Turner wrote:

> Sorry if it caused a headache. It was really a search + replace http://
> to https:// 

However, this needs to be followed by a check of the resulting URL
(some work fine with htpp but not https (because of non-standard
certificates) or, as sourceforge, because they changed the domain for some
https services.
>From the patch and its meta-data I did not find out whether (and to what
extend) you did this checks. So I decided to double-check.

> but I didn't want to do a commit per domain or etc. as it
> would have been many many small commits. 

Fair enough. Still, separating the changes in documentation and code seemed a
good idea to me.

> Didn't realise the MathML point -- all tests passed, but if I changed
> the URL in the test then it is sort of a no-op. 

Changing code and tests in one search + replace operation is dangerous,
because this can lead to both beeing faulty. I made it a habit to only
change the tests after looking at the difference.

Before moving changed documents from "functional/output" to 
"functional/expected", changes also need an additional check:

- convert *.tex documents with `pdflatex` or `xelatex`/`lualatex`
  and inspected the PDF for problems.
- check *.xml documents with `xmllint --valid`
- inspect *.html documents in a browser (or several different browsers)
  and check the validity (the standalone_*html documents have a button in
  the footer for this).

[Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[Pradyun G. <pr...@us...>]

Thanks for the response! This is all good to know.

I asked if there's any updates, primarily because I'm interested in helping out with the migration and willing to do the work. However, it still isn't clear to me that:

(1) the maintainers want to migrate.
(2) what the concerns for doing a migration.
(3) whether my helping hand would be welcome.

I guess it being a TODO item indicates that there's interest in moving to git. That's great, but not what would reduce the barrier enough for me to contribute.

I'd like one of the maintainers to explicitly state whether you're interested in a migration to GitHub. Further, I'd appreciate if a maintainer could elaborate on (2) and (3). It's fine if the answer is "no" or "I don't know" -- even knowing that will be better.

At this point, if I don't get a clear-enough response for these in a reasonable amount of time, I'm going to step away and focus my energy elsewhere.


---

** [feature-requests:#58] Migration Docutils from SourceForge to Github**

**Status:** open
**Group:** Default
**Created:** Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
**Last Updated:** Sat Jan 22, 2022 07:34 AM UTC
**Owner:** nobody


Sourceforge is not really user friendly to report issues, propose pull-request and contribute to the project. I would like to know if it is possible to migrate Docutils to GitHub. 


---

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.

[Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[Pradyun G. <pr...@us...>]

Thanks! I think a contributor using GitHub as part of their workflow is perhaps being yet-another-indicator that docutils will get more contributors if it migrates to GitHub. :)

I appreciate that everyone's got limited time and I didn't intend to be pushy.


---

** [feature-requests:#58] Migration Docutils from SourceForge to Github**

**Status:** open
**Group:** Default
**Created:** Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
**Last Updated:** Sun Jan 16, 2022 04:05 PM UTC
**Owner:** nobody


Sourceforge is not really user friendly to report issues, propose pull-request and contribute to the project. I would like to know if it is possible to migrate Docutils to GitHub. 


---

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.

[Docutils-develop] [docutils:feature-requests] Re: #89 Public API, versioning, and deprecation

[Günter M. <mi...@us...>]

>> in Docutils, the "major" part of the version identifier is incremented
>> "if there is a major change in the design or API" while in Semantic
>> Versioning the "major" part "MUST be incremented if any backwards
>> incompatible changes are introduced to the public API".

> I agree with your summary. The issue is that I think users, downstream
> developers will expect the latter -- having backwards incompatible
> changes in a minor version violates the principle of least surprise. 

> What I proposed is the
> SemVer specification in terms of breaking changes (removals, changes in
> the DTD/default templates/etc), but codifying a deprecation period on
> top of that.

> _____

> I would argue that type annotations and docstrings are orthogonal to
> the public API question -- for developers working on Docutils itself,
> both are helpful!

Docstrings are (at least indirectly) related to public API in PEP 8:

> Documented interfaces are considered public, unless the documentation
> explicitly declares them to be provisional or internal interfaces
> exempt from the usual backwards compatibility guarantees.
> All undocumented interfaces should be assumed to be internal.

----

> Concrete proposal RE public API in code: 

> - Use `__all__` as you proposed for all global names (classes, module level functions, module level variables, etc)

> - Adopt underscores for **new** private names
> - *Consider* introducing underscores for existing names, through `__getattr__` or similar (with full backwards compatability and a deprecation period, and ideally helper functions to mean that downstream users don't need to use internal things as much)

I'd rather not.

> - Don't use type annotations as an indication of status in the public API -- they are too helpful for that. Move to use them everywhere.

I don't insist on type annotations as indicator.
However, adding type annotations to existing code should concentrate on the
public API.

> - Formalise the wording for docstrings for public vs private vs provisional (ideally this would be a single regex pattern).

Agreed.


I'll attach an draft document that tries to sum up what we have reached so
far (work in progress).


---

** [feature-requests:#89] Public API, versioning, and deprecation**

**Status:** open
**Group:** Default
**Created:** Sun Jan 16, 2022 01:39 AM UTC by Adam  Turner
**Last Updated:** Thu Jan 20, 2022 02:27 AM 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.

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.

[Docutils-develop] [docutils:patches] Re: #191 Update URLs

[Adam T. <aa-...@us...>]

Sorry if it caused a headache. It was really a search + replace http:// to https:// but I didn't want to do a commit per domain or etc. as it would have been many many small commits. 

Didn't realise the MathML point -- all tests passed, but if I changed the URL in the test then it is sort of a no-op. 

Thanks for fixing Flake8!

A


---

** [patches:#191] Update URLs **

**Status:** open
**Group:** None
**Created:** Thu Jan 20, 2022 04:40 AM UTC by Adam  Turner
**Last Updated:** Thu Jan 20, 2022 12:09 PM UTC
**Owner:** nobody


Documentation / minor change. 

There are a lot of old URLs in the repo -- e.g. `docutils.sf.net`, `docutils.sourceforge.net` -- whilst these currently still work, we should update them all to the canonical `https://docutils.sourceforge.io` 

This patch does that, and also generally updates several other links to `https://` -- I tested each domain, so didn't update some old sourceforge domains that don't support `https://`. I also updated the `docutils.dtd` IDN in a single commit, so it can be dropped if wanted. 

I'd certainly reccomend applying the first 4 commits, and ideally the entire patch. 

https://github.com/AA-Turner/docutils/pull/10 // https://github.com/AA-Turner/docutils/pull/10.patch

A


---

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.

[Docutils-develop] [docutils:patches] Re: #191 Update URLs

[Günter M. <mi...@us...>]

On 2022-01-20, Adam Turner via Docutils-develop wrote in gmane.text.docutils.devel:

>> Changing the IDN breaks the validity of generated XML documents:

> I thought it was a bit of a riskier change!

>> Commit 6/6 did not apply cleanly here 

> See > https://github.com/AA-Turner/docutils/pull/11.patch for the "clean"
> commit #6

This is a massive change. I split it in documentation vs. code changes,
fixed/updated some more URLs left out changes for "historic" docs, and
dropped the change in MathML namespace specifiers to keep them valid.

...

> Flake8 fails on master with the following errors -- it wasn't anything I introduced

Fixed. Thanks for telling.


Thank you for your contributions.


---

** [patches:#191] Update URLs **

**Status:** open
**Group:** None
**Created:** Thu Jan 20, 2022 04:40 AM UTC by Adam  Turner
**Last Updated:** Thu Jan 20, 2022 12:09 PM UTC
**Owner:** nobody


Documentation / minor change. 

There are a lot of old URLs in the repo -- e.g. `docutils.sf.net`, `docutils.sourceforge.net` -- whilst these currently still work, we should update them all to the canonical `https://docutils.sourceforge.io` 

This patch does that, and also generally updates several other links to `https://` -- I tested each domain, so didn't update some old sourceforge domains that don't support `https://`. I also updated the `docutils.dtd` IDN in a single commit, so it can be dropped if wanted. 

I'd certainly reccomend applying the first 4 commits, and ideally the entire patch. 

https://github.com/AA-Turner/docutils/pull/10 // https://github.com/AA-Turner/docutils/pull/10.patch

A


---

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.

Re: [Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[<jua...@re...>]

GitHub is an American company, and GitLab is hosted on Google Cloud Platform, an American company, and SourceForge is owned by Slashdot Media, an American company. American companies are subject to American laws, in particular regarding trade restrictions and sanctions to other countries[1].


That's the reason why in 2018 GitLab warned its users in Crimea, Cuba, Iran, North Korea, Sudan, and Syria that they might have issues accessing GitLab[2], that's why in 2019 GitHub blocked Iran, Syria, and Crimea[3], and that's why SourceForge is potentially subject to those same regulations and could be requested to enforce them at any time.


This hasn't stopped the large majority of open source projects to move to GitHub, an American company that is blocked or limited in many countries around the world. I made this decision for my own open-source projects as well, no judgment here. Just stating facts.


It is very praiseworthy if docutils as a project wants to take a stance in these conversations. But make no mistake: moving to GitHub will not make things worse than they are now.


If avoiding American trade restrictions is a priority for the docutils project (which I doubt, since, as I said, SourceForge is subject to them as well) and the project ever makes the move to a modern, contributor-friendly platform (which SourceForge isn't), https://codeberg.org/ is hosted in Europe, operated by a German non-profit, and based on Gitea, an open-source clone of GitHub (with fewer bells and whistles of course, but still an improvement over SF). And I'm sure there are other alternatives.



[1]: https://home.treasury.gov/policy-issues/financial-sanctions/sanctions-programs-and-country-information
[2]: https://about.gitlab.com/blog/2018/07/19/gcp-move-update/
[3]: https://techcrunch.com/2019/07/29/github-ban-sanctioned-countries/

Cheers,
ju...@re...
Read the Docs

--- original message ---
On January 21, 2022, 5:30 AM GMT+1 chr...@ho... wrote:



> GitHub is often blocked by companies / agencies because of the sites ties to China



GitHub is owned by Microsoft, so I’m a bit confused by your insertion it has ties to China.
A company could choose to block any site at any time, so I don’t think this should be a consideration.

Also https://github.com/python itself is on GitHub and most core Python tools, so if your company does block GitHub, you are going to find it difficult to do any Python development.



> when the suggested changes are rejected, goes and creates their own Docutils on GitLab or GitHub.



This is the nature of open source programming, and already easily possible.

Moreover, it should be encouraged for people to create forks, if that’s what they require for their own use case.

There can still only be one package under the exact “docutils” name in PyPI.

If open source developers want to “gate-keep” their code, then I would suggest they should not be making their code open source, or change the licensing.


> On 21 Jan 2022, at 04:49, Jeffrey C. Jacobs <dar...@ti...> wrote:


> I would just like to say I use Git a lot and my only reservations are 1) GitHub is often blocked by companies / agencies because of the sites ties to China. I would suggest long term to use GitLab.



> Secondly, Forking isn’t so much a problem if branching isn’t allowed but branching seems more natural. The main thing I worry about is someone activating a pull request which is against the core principles of Docutils and, when the suggested changes are rejected, goes and creates their own Docutils on GitLab or GitHub and submits it to pypi and users don’t know which one is legit. That’s my only other concern. Beyond that, I have no issue with Git but ask you show some patience with David as he’s only just come back to the project in force recently.



> Jeffrey


>> On Sun, Jan 16, 2022 at 16:58 "Günter Milde" via Docutils-develop <doc...@li...> wrote:


>>> The issue not forgotten. You may have a look at 

>>> https://docutils.sourceforge.io/docs/dev/todo.html#repository

>>> for some thoughts (and at the version history at

>>> https://sourceforge.net/p/docutils/code/HEAD/log/?path=/trunk/docutils/docs/dev/todo.txt

>>> to monitor the (admittedly slow) progress).


>>> [feature-requests:#58] Migration Docutils from SourceForge to Github

>>> Status: open

>>> Group: Default

>>> Created: Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier

>>> Last Updated: Sun Jan 16, 2022 04:05 PM UTC

>>> Owner: nobody


>>> Sourceforge is not really user friendly to report issues, propose pull-request and contribute to the project. I would like to know if it is possible to migrate Docutils to GitHub. 


>>> 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.


>>> _______________________________________________

>>> Docutils-develop mailing list

>>> Doc...@li...

>>> https://lists.sourceforge.net/lists/listinfo/docutils-develop


>>> Please use "Reply All" to reply to the list.




> _______________________________________________

> Docutils-develop mailing list

> Doc...@li...

> https://lists.sourceforge.net/lists/listinfo/docutils-develop


> Please use "Reply All" to reply to the list.
--- end of original message ---

[Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[Chris S. <chr...@us...>]

> GitHub is often blocked by companies / agencies because of the sites ties to China

GitHub is owned by Microsoft, so I’m a bit confused by your insertion it has ties to China.
A company could choose to block any site at any time, so I don’t think this should be a consideration.
Also https://github.com/python <https://github.com/python> itself is on GitHub and most core Python tools, so if your company does block GitHub, you are going to find it difficult to do any Python development.

> when the suggested changes are rejected, goes and creates their own Docutils on GitLab or GitHub.

This is the nature of open source programming, and already easily possible.
Moreover, it should be encouraged for people to create forks, if that’s what they require for their own use case.
There can still only be one package under the exact “docutils” name in PyPI.
If open source developers want to “gate-keep” their code, then I would suggest they should not be making their code open source, or change the licensing.

> On 21 Jan 2022, at 04:49, Jeffrey C. Jacobs <dar...@ti...> wrote:
> 
> I would just like to say I use Git a lot and my only reservations are 1) GitHub is often blocked by companies / agencies because of the sites ties to China. I would suggest long term to use GitLab.
> 
> Secondly, Forking isn’t so much a problem if branching isn’t allowed but branching seems more natural. The main thing I worry about is someone activating a pull request which is against the core principles of Docutils and, when the suggested changes are rejected, goes and creates their own Docutils on GitLab or GitHub and submits it to pypi and users don’t know which one is legit. That’s my only other concern. Beyond that, I have no issue with Git but ask you show some patience with David as he’s only just come back to the project in force recently.
> 
> Jeffrey
> 
> On Sun, Jan 16, 2022 at 16:58 "Günter Milde" via Docutils-develop <doc...@li... <mailto:doc...@li...>> wrote:
> The issue not forgotten. You may have a look at 
> https://docutils.sourceforge.io/docs/dev/todo.html#repository <https://docutils.sourceforge.io/docs/dev/todo.html#repository>
> for some thoughts (and at the version history at
> https://sourceforge.net/p/docutils/code/HEAD/log/?path=/trunk/docutils/docs/dev/todo.txt <https://sourceforge.net/p/docutils/code/HEAD/log/?path=/trunk/docutils/docs/dev/todo.txt>
> to monitor the (admittedly slow) progress).
> 
> [feature-requests:#58] <https://sourceforge.net/p/docutils/feature-requests/58/> Migration Docutils from SourceForge to Github
> 
> Status: open
> Group: Default
> Created: Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
> Last Updated: Sun Jan 16, 2022 04:05 PM UTC
> Owner: nobody
> 
> Sourceforge is not really user friendly to report issues, propose pull-request and contribute to the project. I would like to know if it is possible to migrate Docutils to GitHub.
> 
> Sent from sourceforge.net <http://sourceforge.net/> because doc...@li... <mailto:doc...@li...> is subscribed to https://sourceforge.net/p/docutils/feature-requests/ <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. <https://sourceforge.net/p/docutils/admin/feature-requests/options.> Or, if this is a mailing list, you can unsubscribe from the mailing list.
> 
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li... <mailto:Doc...@li...>
> https://lists.sourceforge.net/lists/listinfo/docutils-develop <https://lists.sourceforge.net/lists/listinfo/docutils-develop>
> 
> Please use "Reply All" to reply to the list.
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
> 
> Please use "Reply All" to reply to the list.




---

** [feature-requests:#58] Migration Docutils from SourceForge to Github**

**Status:** open
**Group:** Default
**Created:** Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
**Last Updated:** Sun Jan 16, 2022 04:05 PM UTC
**Owner:** nobody


Sourceforge is not really user friendly to report issues, propose pull-request and contribute to the project. I would like to know if it is possible to migrate Docutils to GitHub. 


---

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.

Re: [Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[Chris S. <chr...@ho...>]

> GitHub is often blocked by companies / agencies because of the sites ties to China

GitHub is owned by Microsoft, so I’m a bit confused by your insertion it has ties to China.
A company could choose to block any site at any time, so I don’t think this should be a consideration.
Also https://github.com/python <https://github.com/python> itself is on GitHub and most core Python tools, so if your company does block GitHub, you are going to find it difficult to do any Python development.

> when the suggested changes are rejected, goes and creates their own Docutils on GitLab or GitHub.

This is the nature of open source programming, and already easily possible.
Moreover, it should be encouraged for people to create forks, if that’s what they require for their own use case.
There can still only be one package under the exact “docutils” name in PyPI.
If open source developers want to “gate-keep” their code, then I would suggest they should not be making their code open source, or change the licensing.

> On 21 Jan 2022, at 04:49, Jeffrey C. Jacobs <dar...@ti...> wrote:
> 
> I would just like to say I use Git a lot and my only reservations are 1) GitHub is often blocked by companies / agencies because of the sites ties to China. I would suggest long term to use GitLab.
> 
> Secondly, Forking isn’t so much a problem if branching isn’t allowed but branching seems more natural. The main thing I worry about is someone activating a pull request which is against the core principles of Docutils and, when the suggested changes are rejected, goes and creates their own Docutils on GitLab or GitHub and submits it to pypi and users don’t know which one is legit. That’s my only other concern. Beyond that, I have no issue with Git but ask you show some patience with David as he’s only just come back to the project in force recently.
> 
> Jeffrey
> 
> On Sun, Jan 16, 2022 at 16:58 "Günter Milde" via Docutils-develop <doc...@li... <mailto:doc...@li...>> wrote:
> The issue not forgotten. You may have a look at 
> https://docutils.sourceforge.io/docs/dev/todo.html#repository <https://docutils.sourceforge.io/docs/dev/todo.html#repository>
> for some thoughts (and at the version history at
> https://sourceforge.net/p/docutils/code/HEAD/log/?path=/trunk/docutils/docs/dev/todo.txt <https://sourceforge.net/p/docutils/code/HEAD/log/?path=/trunk/docutils/docs/dev/todo.txt>
> to monitor the (admittedly slow) progress).
> 
> [feature-requests:#58] <https://sourceforge.net/p/docutils/feature-requests/58/> Migration Docutils from SourceForge to Github
> 
> Status: open
> Group: Default
> Created: Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
> Last Updated: Sun Jan 16, 2022 04:05 PM UTC
> Owner: nobody
> 
> Sourceforge is not really user friendly to report issues, propose pull-request and contribute to the project. I would like to know if it is possible to migrate Docutils to GitHub.
> 
> Sent from sourceforge.net <http://sourceforge.net/> because doc...@li... <mailto:doc...@li...> is subscribed to https://sourceforge.net/p/docutils/feature-requests/ <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. <https://sourceforge.net/p/docutils/admin/feature-requests/options.> Or, if this is a mailing list, you can unsubscribe from the mailing list.
> 
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li... <mailto:Doc...@li...>
> https://lists.sourceforge.net/lists/listinfo/docutils-develop <https://lists.sourceforge.net/lists/listinfo/docutils-develop>
> 
> Please use "Reply All" to reply to the list.
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
> 
> Please use "Reply All" to reply to the list.

[Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[Jeffrey C. J. <tim...@us...>]

I would just like to say I use Git a lot and my only reservations are 1)
GitHub is often blocked by companies / agencies because of the sites ties
to China. I would suggest long term to use GitLab.

Secondly, Forking isn’t so much a problem if branching isn’t allowed but
branching seems more natural. The main thing I worry about is someone
activating a pull request which is against the core principles of Docutils
and, when the suggested changes are rejected, goes and creates their own
Docutils on GitLab or GitHub and submits it to pypi and users don’t know
which one is legit. That’s my only other concern. Beyond that, I have no
issue with Git but ask you show some patience with David as he’s only just
come back to the project in force recently.

Jeffrey

On Sun, Jan 16, 2022 at 16:58 "Günter Milde" via Docutils-develop <
doc...@li...> wrote:

> The issue not forgotten. You may have a look at
> https://docutils.sourceforge.io/docs/dev/todo.html#repository
> for some thoughts (and at the version history at
>
> https://sourceforge.net/p/docutils/code/HEAD/log/?path=/trunk/docutils/docs/dev/todo.txt
> to monitor the (admittedly slow) progress).
> ------------------------------
>
> * [feature-requests:#58]
> <https://sourceforge.net/p/docutils/feature-requests/58/> Migration
> Docutils from SourceForge to Github*
>
> *Status:* open
> *Group:* Default
> *Created:* Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
> *Last Updated:* Sun Jan 16, 2022 04:05 PM UTC
> *Owner:* nobody
>
> Sourceforge is not really user friendly to report issues, propose
> pull-request and contribute to the project. I would like to know if it is
> possible to migrate Docutils to GitHub.
> ------------------------------
>
> 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.
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>



---

** [feature-requests:#58] Migration Docutils from SourceForge to Github**

**Status:** open
**Group:** Default
**Created:** Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
**Last Updated:** Sun Jan 16, 2022 04:05 PM UTC
**Owner:** nobody


Sourceforge is not really user friendly to report issues, propose pull-request and contribute to the project. I would like to know if it is possible to migrate Docutils to GitHub. 


---

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.

Re: [Docutils-develop] [docutils:feature-requests] Re: #58 Migration Docutils from SourceForge to Github

[Jeffrey C. J. <dar...@ti...>]

I would just like to say I use Git a lot and my only reservations are 1)
GitHub is often blocked by companies / agencies because of the sites ties
to China. I would suggest long term to use GitLab.

Secondly, Forking isn’t so much a problem if branching isn’t allowed but
branching seems more natural. The main thing I worry about is someone
activating a pull request which is against the core principles of Docutils
and, when the suggested changes are rejected, goes and creates their own
Docutils on GitLab or GitHub and submits it to pypi and users don’t know
which one is legit. That’s my only other concern. Beyond that, I have no
issue with Git but ask you show some patience with David as he’s only just
come back to the project in force recently.

Jeffrey

On Sun, Jan 16, 2022 at 16:58 "Günter Milde" via Docutils-develop <
doc...@li...> wrote:

> The issue not forgotten. You may have a look at
> https://docutils.sourceforge.io/docs/dev/todo.html#repository
> for some thoughts (and at the version history at
>
> https://sourceforge.net/p/docutils/code/HEAD/log/?path=/trunk/docutils/docs/dev/todo.txt
> to monitor the (admittedly slow) progress).
> ------------------------------
>
> * [feature-requests:#58]
> <https://sourceforge.net/p/docutils/feature-requests/58/> Migration
> Docutils from SourceForge to Github*
>
> *Status:* open
> *Group:* Default
> *Created:* Fri Feb 16, 2018 03:23 PM UTC by Yves Chevallier
> *Last Updated:* Sun Jan 16, 2022 04:05 PM UTC
> *Owner:* nobody
>
> Sourceforge is not really user friendly to report issues, propose
> pull-request and contribute to the project. I would like to know if it is
> possible to migrate Docutils to GitHub.
> ------------------------------
>
> 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.
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

[Docutils-develop] [docutils:patches] #191 Update URLs

[Adam T. <aa-...@us...>]

> Changing the IDN breaks the validity of generated XML documents:

I thought it was a bit of a riskier change!

> Commit 6/6 did not apply cleanly here 

Yeah, commit 6 won't apply if you don't apply #5 -- I kept them apart but should have thought about that, sorry. See https://github.com/AA-Turner/docutils/pull/11 // https://github.com/AA-Turner/docutils/pull/11.patch for the "clean" commit #6

> Maybe this is also why flake8 failed? // flagged "Some checks were not successful"

Flake8 fails on master with the following errors -- it wasn't anything I introduced

```
docutils/frontend.py:389:47: F821 undefined name 'locale_encoding'
docutils/utils/math/latex2mathml.py:861:1: C901 'handle_cmd' is too complex (68)
docutils/utils/math/latex2mathml.py:1210:52: E712 comparison to True should be 'if cond is True:' or 'if cond:'
docutils/utils/math/latex2mathml.py:1221:52: E712 comparison to True should be 'if cond is True:' or 'if cond:'
docutils/utils/math/math2html.py:2350:18: F821 undefined name 'Label'
docutils/utils/math/math2html.py:2353:5: F821 undefined name 'Label'
```

A


---

** [patches:#191] Update URLs **

**Status:** open
**Group:** None
**Created:** Thu Jan 20, 2022 04:40 AM UTC by Adam  Turner
**Last Updated:** Thu Jan 20, 2022 09:57 AM UTC
**Owner:** nobody


Documentation / minor change. 

There are a lot of old URLs in the repo -- e.g. `docutils.sf.net`, `docutils.sourceforge.net` -- whilst these currently still work, we should update them all to the canonical `https://docutils.sourceforge.io` 

This patch does that, and also generally updates several other links to `https://` -- I tested each domain, so didn't update some old sourceforge domains that don't support `https://`. I also updated the `docutils.dtd` IDN in a single commit, so it can be dropped if wanted. 

I'd certainly reccomend applying the first 4 commits, and ideally the entire patch. 

https://github.com/AA-Turner/docutils/pull/10 // https://github.com/AA-Turner/docutils/pull/10.patch

A


---

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.

[Docutils-develop] [docutils:patches] #191 Update URLs

[Günter M. <mi...@us...>]

Thank you for the patch. Most of it is applied now.

Changing the IDN breaks the validity of generated XML documents:

    #test/functional/expected >  xmllint standalone_rst_docutils_xml.xml --valid --noout
    standalone_rst_docutils_xml.xml:4: validity error : Validation failed: no DTD found !
Maybe this is also why flake8 failed? 
https://github.com/AA-Turner/docutils/runs/4877613719?check_suite_focus=true

Commit 6/6 did not apply cleanly here and is also flagged "Some checks were not successful", so I leave it for now.



---

** [patches:#191] Update URLs **

**Status:** open
**Group:** None
**Created:** Thu Jan 20, 2022 04:40 AM UTC by Adam  Turner
**Last Updated:** Thu Jan 20, 2022 04:40 AM UTC
**Owner:** nobody


Documentation / minor change. 

There are a lot of old URLs in the repo -- e.g. `docutils.sf.net`, `docutils.sourceforge.net` -- whilst these currently still work, we should update them all to the canonical `https://docutils.sourceforge.io` 

This patch does that, and also generally updates several other links to `https://` -- I tested each domain, so didn't update some old sourceforge domains that don't support `https://`. I also updated the `docutils.dtd` IDN in a single commit, so it can be dropped if wanted. 

I'd certainly reccomend applying the first 4 commits, and ideally the entire patch. 

https://github.com/AA-Turner/docutils/pull/10 // https://github.com/AA-Turner/docutils/pull/10.patch

A


---

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.