docutils-develop — For developer discussions of the implementation.

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

[Matthew B. <mat...@us...>]

Hi,

On Mon, Nov 15, 2021 at 3:06 PM engelbert gruber via Docutils-develop
<doc...@li...> wrote:
>
> Beats me ... since when is the choice of newbies an argument for going
> that way.

Sorry - just couldn't help it.  I think you will find that a huge
majority of experienced developers would strongly support a switch to
Github, to support _both_ experienced developers, _and_ newbies.
Fortunately for everyone, I can restrain myself from repeating the
arguments as to why I'm sure that is the case.

Cheers,

Matthew


---

** [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:** Mon Nov 15, 2021 03:32 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.

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

[Matthew B. <mat...@gm...>]

Hi,

On Mon, Nov 15, 2021 at 3:06 PM engelbert gruber via Docutils-develop
<doc...@li...> wrote:
>
> Beats me ... since when is the choice of newbies an argument for going
> that way.

Sorry - just couldn't help it.  I think you will find that a huge
majority of experienced developers would strongly support a switch to
Github, to support _both_ experienced developers, _and_ newbies.
Fortunately for everyone, I can restrain myself from repeating the
arguments as to why I'm sure that is the case.

Cheers,

Matthew

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

[engelbert g. <gr...@us...>]

Beats me ...  since when is the choice of newbies an argument for going
that way.

The interesting thing to me is which arguments come up 😂 like the
distributed thing which is no longer valid it seams.

Cheers

Sviatoslav Sydorenko <web...@us...> schrieb am Do., 6.
Aug. 2020, 22:03:

> I'd also like to +1 this request. These days Git is the go-to solution for
> starting projects and keeping them going. In fact, even I've never had to
> learn to use svn. I recall copying some commands back in 2012 to fetch some
> source but then I've never needed it again. Throughout my career I haven't
> met anything other then Git with a few exceptions (like perforce) on
> "neighbor" projects that I didn't participate in.
>
> And since Git became so popular, it's the first thing newbies see in when
> they start figuring out coding in 2020. With time, the number of people who
> know Git (and never saw svn in their lives) and are familiar with the
> popular code hosting / social platforms is going to be overwhelmingly
> higher. Many of them could potentially contribute and help maintain this
> project but wouldn't want to go through all of the burden of learning a
> totally foreign mix of ecosystems.
>
> Now, besides the obvious GitHub/GitHub/BitBucket hostings that provide
> about the same set of the basic colaboration services (like issues/pull
> requests/CI), there's also others that are more open (as in the are all
> FOSS). Let me give you some idea about the options with some notes:
>
>    - https://opendev.org/ — this one comes from the OpenStack ecosystem
>    and consists of a set of open source tools like Gerrit (code review), Zuul
>    (CI — literally the most flexibly configurable of a kind that folks run for
>    FOSS projects), Gitea (browsing source), Etherpad, mediawiki and some more.
>    - https://sr.ht/ — also consists of a collection of tools, connected
>    in an UNIX-style way (componets that follow a single responsibility
>    principle by doing one thing but doing it well). There's a bug tracker,
>    wikis, CI and mailing lists built-in. The most wonderful feature it
>    supports IMHO is the first-class support for email-driven git workflow.
>    This means that contributors don't even need an account on the service —
>    they can send patches over email in a standardized manner (
>    https://drewdevault.com/2018/07/02/Email-driven-git.html /
>    https://git-send-email.io/). Fun fact: Git itself uses an send-email
>    for their own contribution workflow!
>    - https://pagure.io/ — a Git hosting that is mostly used by Fedora and
>    is sponsored by Red Hat. Though, AFAICS it's open to be used by anybody.
>    Also open source. Has some issues/wiki support. Seems to require an
>    external Jenkins instance for CI.
>    - http://github.com/ — issues/Pull Requests/wiki/CI/huge
>    community/project boards. Doesn't have mailing lists, nor is open source
>    itself. Among advantages: big single-click Apps/integrations ecosystem, has
>    a built-in static website hosting (GitHub Pages).
>    - https://gitlab.com/ — (almost) open source. They say it's open core
>    — the main thing is FOSS and extra features are closed/paid. Has
>    issues/Merge Requests/wiki/CI/somewhat big community/GitLab Pages (static
>    website hosting)/Docker registry/project boards.
>    - https://bitbucket.org/ — closed source, has issues/Pull Requests/CI.
>
> ------------------------------
>
> * [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 Aug 02, 2020 05:27 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 you indicated interest in
> https://sourceforge.net/p/docutils/feature-requests/58/
>
> To unsubscribe from further messages, please visit
> https://sourceforge.net/auth/subscriptions/
>



---

** [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:** Mon Nov 15, 2021 03:32 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:bugs] #433 Section headers consisting of unicode characters are not parsed correctly

[Michael S. <sei...@us...>]

Thanks for having at look at this, Günter!

My original understanding was that `len` already reported the correct column width of a string. After reading up on wide Unicode characters and East Asian Character width, the behaviour makes sense to me, though.

The additional explanation you added is great, as it addresses the core of my initial confusion.


---

** [bugs:#433] Section headers consisting of unicode characters are not parsed correctly**

**Status:** closed-invalid
**Labels:** rst parser 
**Created:** Sat Nov 13, 2021 02:07 PM UTC by Michael Seifert
**Last Updated:** Sun Nov 14, 2021 09:44 PM UTC
**Owner:** nobody


I use the Hypothesis framework to generate test data, which ends up being parsed by docutils' rst Parser. If I'm not mistaken, I discovered a bug in docutils r8885 regarding the parsing of section headers.

Consider the following document:
~~~
鄺
=
~~~
When using rst.Parser to parse the document, it reports the warning "Possible title underline, too short for the title. Treating it as ordinary text because it's so short."

However, the length of "鄺" is 1:
~~~
$ python
>>> len("鄺")
1
~~~

The expected behaviour is that 鄺 is recognized as the title of a section.

To reproduce the issue, add the following code to the list of test cases in test_parsers.test_rst.test_section_headers:
~~~
["""\
鄺
=
""",
"""\
<document source="test data">
     <section ids="鄺" names="鄺">
         <title>
             鄺
"""],
~~~

Is this an issue with the parser or did I miss a special case regarding section headers?


---

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.

Re: [Docutils-develop] returning to active development

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

Dear David,

On 2021-11-15, David Goodger wrote:

> I have been neglecting Docutils for too long, lurking but not participating
> much beyond moderating the mailing lists. I am returning to active
> development, slowly at first.

Thank you for taking care of the mailing lists, one of these important but
"invisible" chores.

> I'd like to thank Günter Milde and Engelbert Gruber for maintaining and
> releasing Docutils in my absence. I also want to publicly apologize to
> everyone in the Docutils community, and especially to Engelbert and Günter,
> for my radio silence.

I am fully aware that there is life beyond coding and interest and focus
work may shift over time, so you are welcome.

> Further announcements to come.

Wecome back!

Günter Milde

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

[David G. <go...@us...>]

To everyone who commented on this,

Thank you for your input. You have been heard; no need to keep posting
about this. Please be patient. There will be follow-ups on this (and other
things) before too long.

David Goodger



---

** [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:** Mon Nov 15, 2021 03:32 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.

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

[David G. <go...@py...>]

To everyone who commented on this,

Thank you for your input. You have been heard; no need to keep posting
about this. Please be patient. There will be follow-ups on this (and other
things) before too long.

David Goodger

[Docutils-develop] returning to active development

[David G. <go...@py...>]

I have been neglecting Docutils for too long, lurking but not participating
much beyond moderating the mailing lists. I am returning to active
development, slowly at first.

I'd like to thank Günter Milde and Engelbert Gruber for maintaining and
releasing Docutils in my absence. I also want to publicly apologize to
everyone in the Docutils community, and especially to Engelbert and Günter,
for my radio silence.

Further announcements to come.

David Goodger

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

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

To the docutils maintainers:

As I'm sure you're aware, docutils is a critical tool for Python's documentation ecosystem. I empathize with the fact that migrations are painful, that it will require you to gain familiarity with a new platform, that the benefits seem unclear/non-existent to you and that you've have some bad interactions around this topic.

I'll reiterate my offer to help with the migration. As has been mentioned earlier in this thread (as well as from a thread in 2014 on the docutils-develop mailing list), the migration is feasible and reasonably straightforward.

I hope that you haven't brushed aside all the **positive things about GitHub** that have been mentioned such as the **reduced overhead in maintainer workflows** with automated testing + linting on every commit / pull request (i.e. patch submissions), the **simpler contribution workflow**, significantly **better discoverability**, a much more **modern user interface** and more.

I hope you've noticed that multiple folks have talked how SourceForge is "very outdated", and how it has a "higher barrier to entry". I hope you understand that leads to fewer contributions and lower quality contributions.

I hope you've noticed that the list of folks speaking in favour of migrating to GitHub *and* been a moderating voice in this discussion is *much* longer than that of folks who have been disrespectful.

I hope you won't use a few bad apples, to say that the broader group is disrespectful / unwelcoming.

I hope that you've noticed that nearly everyone has been very respectful and provided detailed responses to your often-terse responses.

I hope that you don't think that "mean people" is representative of the community engaging with you here. We've had many folks with strong feelings have show up to say things here and a very small subset of them have been disrespectful, and other have called them out on it.

I want to point out that the list of folks speaking in favour of migrating includes maintainers from Python Packaging Authority (https://www.pypa.io/en/latest/), ReadTheDocs (https://readthedocs.org/), Executable Books (https://executablebooks.org/en/latest/), Ansible (https://www.ansible.com/), staff from various universities, contributors to Sphinx (https://www.sphinx-doc.org/en/master/) and... I'm still missing a few people whose credentials I don't know/couldn't look up. The list of folks who have said they prefer GitHub to SourceForge is even longer, and includes a Sphinx maintainer.

I'd argue that all of these are folks who are a part of the docutils' existing community and who would be significantly more likely to contribute to the project in a greater capacity, if docutils were on a platform that they were more comfortable using.

Finally, I'll repeat my question from my first post here (which a few folks have mentioned, and other have mentioned that they didn't notice):

> If folks wish to stick with Sourceforge and SVN, on principle of avoiding git because it uses hashes / proprietary software like GitHub / Microsoft owned stuff / "centralisation of open source" / something along those lines, could someone explicitly state that? (These are all things I've read on the mailing list archives for this project, but they're from a decent amount of time ago -- people are definitely entitled to changing their opinions as time passes).

Having clarity on what your concerns are would be great. 

--
Pradyun Gedam

I help maintain critical open source digital infrastructure for Python like pip, PyPI, TOML and more.



---

** [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:** Mon Nov 15, 2021 03:32 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] #58 Migration Docutils from SourceForge to Github

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

I don't know why this needs to be stated explicitly -- uhm... Do not be disrespectful to the maintainers of the project, or their choice of platform. They're choosing what works for them -- if it doesn't work for you, deal with it. By being disrespectful toward the maintainers, you're not helping anyone.

Pardon the metaphor: You don't get to show up to a stranger's house, start by criticising them and their choice of furniture, and then expect that they'd still be willing be to do you a favour.



---

** [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:** Mon Nov 01, 2021 12:35 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:bugs] #433 Section headers consisting of unicode characters are not parsed correctly

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

- **status**: open --> closed-invalid
- **Comment**:

Thanks for sharing your experience with the rST parser.

The reported behaviour is intended but poorly documented.

The [quick reStructuredText help](https://docutils.sourceforge.io/docs/user/rst/quickref.html#section-structure) says:

> The underline/overline must be at least as long as the title text.
  
As always, the devil is in the [detail](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections)

> An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text.

The function checking the lenght of the title adornment adjusts the return value of `len` to account for combining characters on the one side and double-width characters on the other.
This is tested in `test/test_parsers/test_rst/test_east_asian_text.py`.

I hope, an explanatory footnote to the "details" will make this more clear in future:
>The key is the visual length of the title in a mono-spaced font. The adornment may need more or less characters than title, if the title contains wide or combining characters.





---

** [bugs:#433] Section headers consisting of unicode characters are not parsed correctly**

**Status:** closed-invalid
**Labels:** rst parser 
**Created:** Sat Nov 13, 2021 02:07 PM UTC by Michael Seifert
**Last Updated:** Sat Nov 13, 2021 02:07 PM UTC
**Owner:** nobody


I use the Hypothesis framework to generate test data, which ends up being parsed by docutils' rst Parser. If I'm not mistaken, I discovered a bug in docutils r8885 regarding the parsing of section headers.

Consider the following document:
~~~
鄺
=
~~~
When using rst.Parser to parse the document, it reports the warning "Possible title underline, too short for the title. Treating it as ordinary text because it's so short."

However, the length of "鄺" is 1:
~~~
$ python
>>> len("鄺")
1
~~~

The expected behaviour is that 鄺 is recognized as the title of a section.

To reproduce the issue, add the following code to the list of test cases in test_parsers.test_rst.test_section_headers:
~~~
["""\
鄺
=
""",
"""\
<document source="test data">
     <section ids="鄺" names="鄺">
         <title>
             鄺
"""],
~~~

Is this an issue with the parser or did I miss a special case regarding section headers?


---

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] #434 Error when running the test suite for Docutils on Windows 10.

[PotentialUser-54 <pot...@us...>]

---

** [bugs:#434] Error when running the test suite for Docutils on Windows 10.**

**Status:** open
**Labels:** test 
**Created:** Sun Nov 14, 2021 03:34 PM UTC by PotentialUser-54
**Last Updated:** Sun Nov 14, 2021 03:34 PM UTC
**Owner:** nobody


Running the test suite for Docutils on Windows 10 using [the instructions](https://docutils.sourceforge.io/README.html#running-the-test-suite) fails.

As instructed, I am now opening this bug report after checking that there is not already one.

```pwsh
PS <redacted>\docutils\docutils\test> python alltests.py
Traceback (most recent call last):
  File "<redacted>\docutils\docutils\test\alltests.py", line 93, in <module>
    suite = suite()
  File "<redacted>\docutils\docutils\test\alltests.py", line 80, in suite
    suite = package_unittest.loadTestModules(DocutilsTestSupport.testroot,
  File "<redacted>\docutils\docutils\test\package_unittest.py", line 102, in loadTestModules
    module = import_module(mod)
  File "<redacted>\docutils\docutils\test\package_unittest.py", line 133, in import_module
    mod = __import__(name)
  File "<redacted>\docutils\docutils\test\test_error_reporting.py", line 212, in <module>
    class SafeStringTests_locale(unittest.TestCase):
  File "<redacted>\docutils\docutils\test\test_error_reporting.py", line 225, in SafeStringTests_locale
    open(b'\xfc')
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xfc in position 0: invalid start byte
```

```pwsh
PS <redacted>\docutils\docutils\test> python ../tools/quicktest.py --version
quicktest.py (Docutils 0.18 [release])
PS <redacted>\docutils\docutils\test> python --version
Python 3.9.6
```


---

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] #433 Section headers consisting of unicode characters are not parsed correctly

[Michael S. <sei...@us...>]

---

** [bugs:#433] Section headers consisting of unicode characters are not parsed correctly**

**Status:** open
**Labels:** rst parser 
**Created:** Sat Nov 13, 2021 02:07 PM UTC by Michael Seifert
**Last Updated:** Sat Nov 13, 2021 02:07 PM UTC
**Owner:** nobody


I use the Hypothesis framework to generate test data, which ends up being parsed by docutils' rst Parser. If I'm not mistaken, I discovered a bug in docutils r8885 regarding the parsing of section headers.

Consider the following document:
~~~
鄺
=
~~~
When using rst.Parser to parse the document, it reports the warning "Possible title underline, too short for the title. Treating it as ordinary text because it's so short."

However, the length of "鄺" is 1:
~~~
$ python
>>> len("鄺")
1
~~~

The expected behaviour is that 鄺 is recognized as the title of a section.

To reproduce the issue, add the following code to the list of test cases in test_parsers.test_rst.test_section_headers:
~~~
["""\
鄺
=
""",
"""\
<document source="test data">
     <section ids="鄺" names="鄺">
         <title>
             鄺
"""],
~~~

Is this an issue with the parser or did I miss a special case regarding section headers?


---

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.

Re: [Docutils-develop] Column number for directive content / nodes in general

[Mickey E. <mic...@pr...>]

Dear all

I did not receive any reaction to my mail. Should I conclude that the outlined approach points in an unfavourable direction?

Regards
Mickey

[Docutils-develop] [docutils:feature-requests] #60 Allow definition_list_item to have multiple terms

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

Do you mean:
~~~
--- a/docutils/docs/ref/docutils.dtd
+++ b/docutils/docs/ref/docutils.dtd
@@ -397,7 +397,7 @@ Eventual replacement for docinfo? -->
 <!ELEMENT definition_list (definition_list_item+)>
 <!ATTLIST definition_list %basic.atts;>
 
-<!ELEMENT definition_list_item (term, classifier*, definition)>
+<!ELEMENT definition_list_item (term+, classifier*, definition)>
 <!ATTLIST definition_list_item %basic.atts;>
 
 <!ELEMENT term %text.model;>
~~~
(plus the matching change in docs/ref/doctree.txt) ?

We would need to check, that all writers can handle the case

    <definition_list>
        <definition_list_item>
            <term>term 1</term>
            <term>term 2</term>
            <definition>
                <paragraph>Definition of both terms.</paragraph>
            </definition>
        </definition_list_item>
    </definition_list>
    
No problem for HTML5, XML, pseudoXML, and LaTeX.
Could you test export of such a Doctree with ODF/ODT, HTML4, manpage writers?

If implemented, this could be coupled with an input convention with empty comment:

    term 1
        ..
    term 2
       Definition of both terms.




---

** [feature-requests:#60] Allow definition_list_item to have multiple terms**

**Status:** open
**Group:** Default
**Created:** Thu Jan 03, 2019 09:10 AM UTC by Takeshi KOMIYA
**Last Updated:** Thu Jan 03, 2019 09:10 AM UTC
**Owner:** nobody
**Attachments:**

- [support_multiple_terms_on_definition_list_item.patch](https://sourceforge.net/p/docutils/feature-requests/60/attachment/support_multiple_terms_on_definition_list_item.patch) (3.7 kB; application/octet-stream)


In HTML  spec, definition list accepts multiple terms in a item.  This patch allows doctree model to have multiple terms as children of definition_list_item also.
https://www.w3.org/TR/html52/grouping-content.html#the-dl-element

In sphinx, a custom directive named "glossary" allows multiple terms for one definition_list_item.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary


---

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] #84 Allow optional and repeating arguments

[Alkis G. <al...@us...>]

Thank you very much Günter! Unfortunately in the meantime and after evaluating both restructuredtext and markdown, I decided that markdown is a better match for my projects and I already started using it (e.g. in https://ltsp.org).
So feel free to close this issue, as I don't think I'll be able to allocate enough free time to propose a patch for it. Of course if anyone needs it, they're most welcome to offer one!


---

** [feature-requests:#84] Allow optional and repeating arguments**

**Status:** open
**Group:** Default
**Created:** Mon Nov 01, 2021 05:44 PM UTC by Alkis Georgopoulos
**Last Updated:** Fri Nov 12, 2021 09:37 AM UTC
**Owner:** nobody


The [option-lists specs](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists) state that "the syntax for short and long POSIX options is based on the syntax supported by Python's [getopt.py](https://docs.python.org/3/library/getopt.html) module".

This doesn't allow for optional or repeating arguments. A couple of examples from the [man man page](https://manpages.debian.org/bullseye/man-db/man.1.en.html#OPTIONS):

```shell
--warnings[=warnings]  This is an argument with an optional value

-m system[,...]  This is an argument with a repeating value
```

My feature request is for the square brackets `[]` to become allowed in the option lists spec and implementation in a similar way as the less than / great than symbols `<>`.

This will allow us to use docutils even when some binaries in our project do need optional or repeating arguments.
(I'm currently evaluating if it would be appropriate to migrate the https://ltsp.org and https://epoptes.org documentation and [man pages](https://ltsp.org/man/ltsp-image/), from markdown to restructuredtext)


---

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] #84 Allow optional and repeating arguments

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

Thank you for the suggestion. I agree that this would be a helpful addition.
A suggestion/patch how to document this feature in the [reStructuredText specification](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists) is welcome.

We have to think about backwards incompatibility, as currently the source text

    --warnings[=warnings]
           Enable warnings from groff.  This may be  used  to  perform
           sanity checks on the source text of manual pages.

is recognised as a definition list item.    (The  the last example in
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists) was added after a user reported tripping over this ambiguity.)
This means we would need an andvance warning and proper documentation, if the request should be implemented.




---

** [feature-requests:#84] Allow optional and repeating arguments**

**Status:** open
**Group:** Default
**Created:** Mon Nov 01, 2021 05:44 PM UTC by Alkis Georgopoulos
**Last Updated:** Mon Nov 01, 2021 05:44 PM UTC
**Owner:** nobody


The [option-lists specs](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists) state that "the syntax for short and long POSIX options is based on the syntax supported by Python's [getopt.py](https://docs.python.org/3/library/getopt.html) module".

This doesn't allow for optional or repeating arguments. A couple of examples from the [man man page](https://manpages.debian.org/bullseye/man-db/man.1.en.html#OPTIONS):

```shell
--warnings[=warnings]  This is an argument with an optional value

-m system[,...]  This is an argument with a repeating value
```

My feature request is for the square brackets `[]` to become allowed in the option lists spec and implementation in a similar way as the less than / great than symbols `<>`.

This will allow us to use docutils even when some binaries in our project do need optional or repeating arguments.
(I'm currently evaluating if it would be appropriate to migrate the https://ltsp.org and https://epoptes.org documentation and [man pages](https://ltsp.org/man/ltsp-image/), from markdown to restructuredtext)


---

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:bugs] #431 docutils 0.18 - Error when using legacy Sphinx package

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

- **status**: closed-wont-fix --> open-fixed
- **Comment**:

r8885 restores the backwards compatibility of nodes.Node.traverse(). 
The new method nodes.Node.findall() returns an iterator for fast and memory efficient looping.

Sphinx versions 1.x should work as before.
Sphinx  >= 2.0 defaults to the provisional "html5" writer: CSS style sheets may require adaption to changed output (more semantic and accessible HTML).

Thanks for the feedback and sorry for the troubles.



---

** [bugs:#431] docutils 0.18 - Error when using legacy Sphinx package **

**Status:** open-fixed
**Created:** Wed Oct 27, 2021 09:47 AM UTC by Lital Yair
**Last Updated:** Fri Nov 05, 2021 02:35 PM UTC
**Owner:** nobody


Hi All

We are using Sphinx version 3.1.2 and version 1.7.6 in 2 different services, and since today we have had errors when we try to build the documentation of those projects.

This is the error:
Exception occurred:
  File "/codebuild/output/src746283639/src/.python/lib/python3.8/site-packages/docutils/writers/html5_polyglot/__init__.py", line 445, in section_title_tags
    if (ids and self.settings.section_self_link
AttributeError: 'Values' object has no attribute 'section_self_link'

The issues are solved when we directly add the previous version of 'docutils' (0.17) to our docs requirements.

Any help will be much appreciated.
Thanks, Lital


---

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] #431 docutils 0.18 - Error when using legacy Sphinx package

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

- **summary**: docutils 0.18 - Error when using Sphinx package  --> docutils 0.18 - Error when using legacy Sphinx package 
- **status**: pending-out-of-date --> closed-wont-fix
- **Comment**:

For possible resolutions, see  the Sphinx feature request
https://github.com/sphinx-doc/sphinx/issues/9807.



---

** [bugs:#431] docutils 0.18 - Error when using legacy Sphinx package **

**Status:** closed-wont-fix
**Created:** Wed Oct 27, 2021 09:47 AM UTC by Lital Yair
**Last Updated:** Sat Oct 30, 2021 09:47 PM UTC
**Owner:** nobody


Hi All

We are using Sphinx version 3.1.2 and version 1.7.6 in 2 different services, and since today we have had errors when we try to build the documentation of those projects.

This is the error:
Exception occurred:
  File "/codebuild/output/src746283639/src/.python/lib/python3.8/site-packages/docutils/writers/html5_polyglot/__init__.py", line 445, in section_title_tags
    if (ids and self.settings.section_self_link
AttributeError: 'Values' object has no attribute 'section_self_link'

The issues are solved when we directly add the previous version of 'docutils' (0.17) to our docs requirements.

Any help will be much appreciated.
Thanks, Lital


---

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.

Re: [Docutils-develop] docutils beta release 0.18b1 out

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

On 2021-10-25, Guenter Milde via Docutils-develop wrote:
> Am 24. Oktober 2021 22:30:32 MESZ schrieb Chris Sewell

>>It would be good practice to provide a proper deprecation pathway, when fundamentally changing the interface.

> I have a slightly different understanding of a *fundamental* change, but...

>>Change the “new” `def traverse` to `def traverse_iter`, then add something like:

>>```
>>def traverse(*args, **kwargs):
>>    warnings.warn(“traverse is now deprecated, please use traverse_iter”)
>>    return list(traverse_iter(*args, **kwargs)
>>```

> this is what we did in Docutils 0.17
> (modulo the warning) but with an advance warning in the RELEASE-NOTES.

We actually also *had* the warning:
https://github.com/sphinx-doc/sphinx/issues/9727#issuecomment-953348638

Introduced 2019-09-18 in https://sourceforge.net/p/docutils/code/8393
with a fixup in https://sourceforge.net/p/docutils/code/8445.


OTOH, this will not help users that have an RTD project that was created
prior to October 2020, RTD will default to sphinx<2, unless you
explicitly specify a version of Sphinx to use.


Günter

[Docutils-develop] [docutils:bugs] #430 avoid mutables as default functions arguments

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

- **labels**:  --> rst parser
- **assigned_to**: Günter Milde



---

** [bugs:#430] avoid mutables as default functions arguments**

**Status:** open
**Labels:** rst parser 
**Created:** Mon Oct 25, 2021 09:53 AM UTC by Dimitri Papadopoulos
**Last Updated:** Tue Nov 02, 2021 02:08 PM UTC
**Owner:** Günter Milde


Mutables shouldn't be used as default parameters, it is a Python anti-pattern. See for example:
* [Default Parameter Values in Python](https://web.archive.org/web/20200221224620/http://effbot.org/zone/default-values.htm)
* [Python Mutable Defaults Are The Source of All Evil](https://florimond.dev/en/posts/2018/08/python-mutable-defaults-are-the-source-of-all-evil/)
* [The Hitchhiker's Guide to Python - Common Gotchas](https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments)
* [Python Pitfall: Mutable Default Arguments](https://towardsdatascience.com/python-pitfall-mutable-default-arguments-9385e8265422)

Mutable default arguments are used in a few places in docutils. Just grep `=[]` and `={}` and retain function definitions.

Mutable default arguments can also be found in the documentation:
https://docutils.sourceforge.io/docs/howto/rst-roles.html#define-the-role-function
https://docutils.sourceforge.io/docs/howto/rst-roles.html#rfc-reference-role

Of course, that's not an immediate problem if the mutable arguments are actually not mutated by the function, but it remains an anti-pattern that may create problems in the future.


---

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] #430 avoid mutables as default functions arguments

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

Thank you for the report and proposal.
Attached is a patch against revision 8874 in the code repository.
As the bug may also be considered just a styling issue and the patch has the potential to break compatibility for 3rd party users, it will have to wait for review and discussion on the way ahead
(inclusion no earlier than 0.19 or 1.0).


Attachments:

- [0001-Avoid-mutables-as-default-functions-arguments.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/125aed801b/38e8/attachment/0001-Avoid-mutables-as-default-functions-arguments.patch) (11.2 kB; text/x-patch)


---

** [bugs:#430] avoid mutables as default functions arguments**

**Status:** open
**Created:** Mon Oct 25, 2021 09:53 AM UTC by Dimitri Papadopoulos
**Last Updated:** Mon Oct 25, 2021 10:28 AM UTC
**Owner:** nobody


Mutables shouldn't be used as default parameters, it is a Python anti-pattern. See for example:
* [Default Parameter Values in Python](https://web.archive.org/web/20200221224620/http://effbot.org/zone/default-values.htm)
* [Python Mutable Defaults Are The Source of All Evil](https://florimond.dev/en/posts/2018/08/python-mutable-defaults-are-the-source-of-all-evil/)
* [The Hitchhiker's Guide to Python - Common Gotchas](https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments)
* [Python Pitfall: Mutable Default Arguments](https://towardsdatascience.com/python-pitfall-mutable-default-arguments-9385e8265422)

Mutable default arguments are used in a few places in docutils. Just grep `=[]` and `={}` and retain function definitions.

Mutable default arguments can also be found in the documentation:
https://docutils.sourceforge.io/docs/howto/rst-roles.html#define-the-role-function
https://docutils.sourceforge.io/docs/howto/rst-roles.html#rfc-reference-role

Of course, that's not an immediate problem if the mutable arguments are actually not mutated by the function, but it remains an anti-pattern that may create problems in the future.


---

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] Backwards copatibility policy (was: docutils beta release 0.18b1 out)

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

Dear Docutils developers,

On 2021-10-25, Chris Sewell wrote:

> As I have already suggested, the use of `DeprecationWarning` would be a
> best practice; following https://www.python.org/dev/peps/pep-0387/

As part of the preparations for release 1.0, I would like to add 
a Backwards Compatibility Policy section to our
`Docutils Project Policies`__.

In the simplest case, we could just reference PEP 387 and start applying
DeprecationWarnings and marking experimental/obsolete/evolving parts as
"provisional".

What is your opinion? What else do we need?

Thanks
Günter

__ https://docutils.sourceforge.io/docs/dev/policies.html

[Docutils-develop] [docutils:feature-requests] #84 Allow optional and repeating arguments

[Alkis G. <al...@us...>]

---

** [feature-requests:#84] Allow optional and repeating arguments**

**Status:** open
**Group:** Default
**Created:** Mon Nov 01, 2021 05:44 PM UTC by Alkis Georgopoulos
**Last Updated:** Mon Nov 01, 2021 05:44 PM UTC
**Owner:** nobody


The [option-lists specs](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists) state that "the syntax for short and long POSIX options is based on the syntax supported by Python's [getopt.py](https://docs.python.org/3/library/getopt.html) module".

This doesn't allow for optional or repeating arguments. A couple of examples from the [man man page](https://manpages.debian.org/bullseye/man-db/man.1.en.html#OPTIONS):

```shell
--warnings[=warnings]  This is an argument with an optional value

-m system[,...]  This is an argument with a repeating value
```

My feature request is for the square brackets `[]` to become allowed in the option lists spec and implementation in a similar way as the less than / great than symbols `<>`.

This will allow us to use docutils even when some binaries in our project do need optional or repeating arguments.
(I'm currently evaluating if it would be appropriate to migrate the https://ltsp.org and https://epoptes.org documentation and [man pages](https://ltsp.org/man/ltsp-image/), from markdown to restructuredtext)


---

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

[Tim H. <t_h...@us...>]

Dear docutils developers, I'm bringing this up one final time because docutils is a very important project to the python ecosystem and because I care a lot about it's documentation infrastructure. I strongly believe that migrating would make work for maintainers and people wanting to contribute easier. (You don't have to follow that opinion, but it's the motivation why people bring this up again and again).

To resolve the issue once and for all, I'd like to draw the attention back to the simple question by @Pradyon Gedam:

> Is there any interest amongst the maintainers/existing contributors to move away from Sourceforge?

**If there is no interest, please state this very clearly and close the topic.** Otherwise people will bring up the topic again and again. And to be clear: No interest is a legitimate choice. 
Ideally, accompany the statement with a short explanation so that people can understand your reasons. All reasons for the choice are legitimate (from sourceforge is good enough for us, over we are not interested in more community engagement/cannot handle the associated work up to we don't have the time to migrate; or anything else). 

**If moving is something you might consider,** but there are still some doubts or practical problems, I'm sure we'll find enough **people willing to help** in various ways; be it answering questions, showing how to work with other platforms, supporting the actual migration, possibly up to organizing financial sponsorhip if that should be a limiting factor. We have a strong community and can achieve much if there is interest!


---

** [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:** Tue Oct 19, 2021 07:11 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.