Bring restbuilder up-to-date: seeking maintainer about restbuilder HOT 10 CLOSED

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

from restbuilder.

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 #2 that @ahakanbaba wanted a bump in the version, although maybe that's not needed anymore.

from restbuilder.

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.

from restbuilder.

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.

from restbuilder.

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

from restbuilder.

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

from restbuilder.

from restbuilder.

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.

from restbuilder.

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)

from restbuilder.

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.

from restbuilder.