Bring restbuilder up-to-date: seeking maintainer

[macfreek]

I just received a message from @chrisjbremner asking me to push a Python3 compatible version to Pypi. Sure can do, I just have to look into it, since it has been a while since I wrote this code. Will probably take me 1 or 2 weeks due to some work deadlines.

But since there is some interest, I'm happy to bring it in a state where others can more easily use it.

That brings me to another point -- I like to move this forward, but reality is that is not very high priority for me. So, if there are other people willing to maintain this project, now would be a good time to step forward!

If none steps forward, I'm happy to do it in the background, but I think this project may need a bit more love (and some more unit tests) :)

The only recent contribution is a fork by @gnidan, but perhaps others are interested. Let me know.

[chrisjbremner]

Thanks for the response @macfreek. I realized soon after I send the message that what I was trying to do is actually covered by vanilla Sphinx already, so I actually don't need the version bumped. It seemed like from https://github.com/sphinx-contrib/restbuilder/issues/2 that @ahakanbaba wanted a bump in the version, although maybe that's not needed anymore.

[macfreek]

A bump is best, as well as other bugs fixes. (There is a reason why the release had version 0.1).

For now, I contacted @stephenfin (owner of the sphinx-contrib group and thus this repository for write access), so I can make a release and make it easier for people to contribute from an up-to-date repository.

I also created a pull request with recent contributions (apparently github allows non-authors to make pull requests of other peoples contribution). At least this way, the code contribution remains clear.

[macfreek]

Version 0.2 is now tagged as such, all known forks pulled in, and the code uploaded to PyPi.

The project still could use a bit of love and attention, so I leave this issue open for another month or so for someone to step forward.

[mortenvp]

@macfreek First of all thanks for the work here. Any news on bringing in an active maintainer - I think there are two open pull-request solving an overlapping issue with the image directive. Would be awesome if these could be merged in.

[adam2392]

@macfreek hi just wanted to see if there was any update on this? Having a sphinx autobuild out rst files instead of html files would be great to have.

[macfreek]

Hi @adam2392, thanks for the inquiry.

It seems that the fork of @davidfritzsche (https://github.com/davidfritzsche/sphinx-rst-builder/) is most up-to-date, so I dropped him an email asking if he would like to take the maintainer role. Unfortunately, I received no reply yet, so he might be busy. That said, I am going to recommend that branch, with one caveat: he renamed the repository.

The two pull requests both concern how external images are handled. However, their logic is slightly different:

6 by @anthonyray uses the logic: target → alt → else

8 by @jesteria use the logic: alt → uri → else

Other branches seem to use alt → uri → else logic, so my initial thought was to go for that option (either ignoring #6, or first committing #6 and overwriting by #8 to give credit were due).

A undecided question is if sphinxcontrib.restbuilder should be renamed to sphinx-rst-builder, like @davidfritzsche did. There are a few pros and cons to this, which I list in a separate issue, #9). I didn't really like it at first (due backward incompatibility), but when trying to write a small test script to verify it the above two PR worked well, bumped into the intrinsics of it. So I'm now more in favour.

So my questions:

• do you concur that @davidfritzsche fork is the most advanced, and I should be followed? (Preferably with him as maintainer, but if not, the improvements can be cloned here).
• do you think that this module should be renamed to sphinx-rst-builder, or keep the sphinxcontrib.restbuilder name? (see #9).

[DavidFritsche]

I don’t think you intended to send this to me. I’m following OHDSI, but only in the most superficial way thus far. I think there’s a ‘z’ in the davidfritzsche that you are looking for!

Best regards, Dave

David P Fritsche Pantograph Group Managing Director M: 508-654-3874 dpfritsche@icloud.com

Biopharma IT Strategy and Consulting

On Jun 14, 2020, at 8:39 AM, Freek Dijkstra notifications@github.com wrote:

 Hi @adam2392, thanks for the inquiry.

It seems that the fork of @DavidFritsche (https://github.com/davidfritzsche/sphinx-rst-builder/) is most up-to-date, so I dropped him an email asking if he would like to take the maintainer role. Unfortunately, I received no reply yet, so he might be busy. That said, I am going to recommend that branch, with one caveat: he renamed the repository.

The two pull requests both concern how external images are handled. However, their logic is slightly different:

6 by @anthonyray uses the logic: target → alt → else

8 by @jesteria use the logic: alt → uri → else

Other branches seem to use alt → uri → else logic, so my initial thought was to go for that option (either ignoring #6, or first committing #6 and overwriting by #8 to give credit were due).

A undecided question is if sphinxcontrib.restbuilder should be renamed to sphinx-rst-builder, like @DavidFritsche did. There are a few pros and cons to this, which I list in a separate issue, #9). I didn't really like it at first (due backward incompatibility), but when trying to write a small test script to verify it the above two PR worked well, bumped into the intrinsics of it. So I'm now more in favour.

So my questions:

do you concur that @davidfritzsche fork is the most advanced, and I should be followed? (Preferably with him as maintainer, but if not, the improvements can be cloned here). do you think that this module should be renamed to sphinx-rst-builder, or keep the sphinxcontrib.restbuilder name? (see #9). — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[macfreek]

I don’t think you intended to send this to me. [...] I think there’s a ‘z’ in the davidfritzsche that you are looking for!

Oops, you're right! My apologies, and thanks for pointing this out. I fixed it in the comment above.

[adam2392]

Hi @adam2392, thanks for the inquiry.

It seems that the fork of @DavidFritzsche (https://github.com/davidfritzsche/sphinx-rst-builder/) is most up-to-date, so I dropped him an email asking if he would like to take the maintainer role. Unfortunately, I received no reply yet, so he might be busy. That said, I am going to recommend that branch, with one caveat: he renamed the repository.

I tried using his repo and tbh I am not an expert at sphinx, so could not get it to work when adding it into conf.py with:

sys.path.append('./sphinx-rst-builder/build/')

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.ifconfig",
    "sphinx.ext.viewcode",
    "sphinx.ext.githubpages",
    "sphinx.ext.intersphinx",
    "sphinx.ext.todo",
    "sphinx.ext.coverage",
    "sphinx.ext.mathjax",
    "sphinx.ext.autosummary",
    # "sphinx_gallery.gen_gallery",
    "numpydoc",
    'sphinx_click.ext',
    'sphinx-rst-builder'
]

So my questions:

• do you concur that @davidfritzsche fork is the most advanced, and I should be followed? (Preferably with him as maintainer, but if not, the improvements can be cloned here).

I concur if that is possible. Do you know if there's any movement on here? i see that he hasn't made any commits recently :(.

• do you think that this module should be renamed to sphinx-rst-builder, or keep the sphinxcontrib.restbuilder name? (see #9).

I like sphinx-rst-builder because that is more explicit that it is for .rst files, whereas restbuilder can read differently.

(non-author edit: fix @-reference)

[macfreek]

I reached out to David Fritzsche again by email, but feel this repository is now in a state that we can call it "maintained". (With help from @jackburridge and some gentle nudges from @nedbat and of course all previous contributors). I think that all features in the @davidfritzsche fork are now covered here as well, and with increased testing, we're sure it will stay that way across all versions of Sphinx and Python (ranging from Sphinx 1.4 to 3.4 (4.x coming shortly) and Python 2.7 to 3.9 (3.10 coming shortly)).

If there are any other missing features or remaining bugs (which there certainly are!), do create an issue. While I can't make promises, I try to look into the ones reported here.

If it has priority, please create a pull request. If the PR validates on Github, I will try to merge it within a week. If I haven't responded in that time, it is easy enough to find my contact details, or simply tag me with @macfreek.

For those who like to contribute code, there are now some (hopefully) helpful comment in CONTRIBUTING.rst .

Finally, as for the naming for "sphinxcontrib-restbuilder" versus "sphinx-rst-builder", I have decided for now to leave it as-is, mostly because @davidfritzsche has published a package on PyPI with that name. Renaming this here will likely lead to more confusion. I'll try to add the word "RST" and "reStructuredText" a bit more often in headlines and subtitles. Hopefully that will help potential users find this repository.