Skip to content
This repository has been archived by the owner on Nov 17, 2022. It is now read-only.

[fix] TypeError coming from suffix arg removed from sphinx v3.0.0 #55

Open
wants to merge 1 commit into
base: dev
Choose a base branch
from

Conversation

CrossNox
Copy link

@CrossNox CrossNox commented Apr 6, 2020

Since 1.8.0, the suffix argument for app.add_source_parser() has been deprecated. And it is removed now.

Fix and mantain backwards compatibility for older sphinx versions.

Closes #51

Comment on lines +652 to 656
try:
app.add_source_parser('.md', M2RParser) # for older sphinx versions
except TypeError:
app.add_source_suffix('.md', 'markdown')
app.add_source_parser(M2RParser)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if add_source_parser and add_source_suffix should be treated differently altogether:

Suggested change
try:
app.add_source_parser('.md', M2RParser) # for older sphinx versions
except TypeError:
app.add_source_suffix('.md', 'markdown')
app.add_source_parser(M2RParser)
if hasattr(app, 'add_source_suffix'):
app.add_source_suffix('.md', 'markdown')
try:
app.add_source_parser('.md', M2RParser) # for older sphinx versions
except TypeError:
app.add_source_parser(M2RParser)

bdewilde added a commit to chartbeat-labs/textacy that referenced this pull request Apr 9, 2020
the m2r extension isn't compatible with v3.0; see miyakogi/m2r#55 for example
@matthewfeickert
Copy link

@miyakogi If you get time to review this it would be great.

ErlendHaa added a commit to ErlendHaa/dlisio that referenced this pull request Apr 17, 2020
The release of sphinx 3.0.0 removed some functions that's been
deprecated since v1.4. This made the sphinx-extension 'm2r' break. We
use m2r to include .md files in the sphinx-docs. Although a PR that
seemingly solves the problem is proposed [1], the sole developer of m2r
has not been active in a while. It's unknown when and if this fix will
be merge and even if, having a dependency on a unmaintained project like
m2r makes me feel a bit uneasy.

The ideal action would be to use 'recommonmark' for our .md files.
However, sphinx and recommonmark does not play nice when the .md files
is out of directory, i.e. outside python/docs [2].

That leaves us with two options, either pinning the sphinx version <
3.0.0 and wait for better days, with regards better sphinx/recommonmarks
support, or port the CHANGELOG to rst. As it's unknown whether [2] will
actually see the day of light or not, porting seems most reasonable at
this point in time.

To mention it, there is a bias against using .rst for CHANGELOGs and
READMEs in the community, with the main points being; 'people are
generally more familiar. md' and '.md is easier and faster to write'.
But with a already well-defined structure to our CHANGELOG, the overhead
is minimal.

[1] miyakogi/m2r#55
[2] sphinx-doc/sphinx#7000
ErlendHaa added a commit to ErlendHaa/dlisio that referenced this pull request Apr 17, 2020
The release of sphinx 3.0.0 removed some functions that's been
deprecated since v1.4. This made the sphinx-extension 'm2r' break. We
use m2r to include .md files in the sphinx-docs. Although a PR that
seemingly solves the problem is proposed [1], the sole developer of m2r
has not been active in a while. It's unknown when and if this fix will
be merge and even if, having a dependency on a unmaintained project like
m2r makes me feel a bit uneasy.

The ideal action would be to use 'recommonmark' for our .md files.
However, sphinx and recommonmark does not play nice when the .md files
is out of directory, i.e. outside python/docs [2].

That leaves us with two options, either pinning the sphinx version <
3.0.0 and wait for better days, with regards better sphinx/recommonmarks
support, or port the CHANGELOG to rst. As it's unknown whether [2] will
actually see the day of light or not, porting seems most reasonable at
this point in time.

To mention it, there is a bias against using .rst for CHANGELOGs and
READMEs in the community, with the main points being that people are
generally more familiar with .md and that .md is easier and faster to
write.  But with a already well-defined structure to our CHANGELOG, the
overhead is minimal.

[1] miyakogi/m2r#55
[2] sphinx-doc/sphinx#7000
ErlendHaa added a commit to ErlendHaa/dlisio that referenced this pull request Apr 17, 2020
The release of sphinx 3.0.0 removed some functions that's been
deprecated since v1.4. This made the sphinx-extension 'm2r' break. We
use m2r to include .md files in the sphinx-docs. Although a PR that
seemingly solves the problem is proposed [1], the sole developer of m2r
has not been active in a while. It's unknown when and if this fix will
be merge and even if, having a dependency on a unmaintained project like
m2r makes me feel a bit uneasy.

The ideal action would be to use 'recommonmark' for our .md files.
However, sphinx and recommonmark does not play nice when the .md files
is out of directory, i.e. outside python/docs [2].

That leaves us with two options, either pinning the sphinx version to
<v3.0.0 and wait for better days, with regards to better
sphinx/recommonmarks support, or port the CHANGELOG to rst. As it's
unknown whether [2] will actually see the day of light or not, porting
seems most reasonable at this point in time.

To mention it, there is a bias against using .rst for CHANGELOGs and
READMEs in the community, with the main points being that people are
generally more familiar with .md and that .md is easier and faster to
write.  But with a already well-defined structure to our CHANGELOG, the
overhead is minimal.

[1] miyakogi/m2r#55
[2] sphinx-doc/sphinx#7000
ErlendHaa added a commit to ErlendHaa/dlisio that referenced this pull request Apr 20, 2020
The release of sphinx 3.0.0 removed some functions that's been
deprecated since v1.4. This made the sphinx-extension 'm2r' break. We
use m2r to include .md files in the sphinx-docs. Although a PR that
seemingly solves the problem is proposed [1], the sole developer of m2r
has not been active in a while. It's unknown when and if this fix will
be merge and even if, having a dependency on a unmaintained project like
m2r makes me feel a bit uneasy.

The ideal action would be to use 'recommonmark' for our .md files.
However, sphinx and recommonmark does not play nice when the .md files
is out of directory, i.e. outside python/docs [2].

That leaves us with two options, either pinning the sphinx version to
<v3.0.0 and wait for better days, with regards to better
sphinx/recommonmarks support, or port the CHANGELOG to rst. As it's
unknown whether [2] will actually see the day of light or not, porting
seems most reasonable at this point in time.

To mention it, there is a bias against using .rst for CHANGELOGs and
READMEs in the community, with the main points being that people are
generally more familiar with .md and that .md is easier and faster to
write.  But with a already well-defined structure to our CHANGELOG, the
overhead is minimal.

[1] miyakogi/m2r#55
[2] sphinx-doc/sphinx#7000
cattabiani pushed a commit to BlueBrain/nmodl that referenced this pull request Apr 22, 2020
  in m2r: miyakogi/m2r#55)
- add path in conf.py to find the nmodl module
- removed various doxygen warnings due to unacceptable keywords
  in configuration files
- adjust checkparent_visitor sphinx autodoc /copybrief
- reduce the maxium number of processors used to build documentation
  (it was freezing my workstation)
cattabiani pushed a commit to BlueBrain/nmodl that referenced this pull request Apr 22, 2020
- m2r & sphinx>=3.0 are not compatible (more info in pr in progress
  in m2r: miyakogi/m2r#55)
- add path in conf.py to find the nmodl module
- removed various doxygen warnings due to unacceptable keywords
  in configuration files
- adjust checkparent_visitor sphinx autodoc /copybrief
- reduce the maxium number of processors used to build documentation
  (it was freezing my workstation)
cattabiani added a commit to BlueBrain/nmodl that referenced this pull request Apr 24, 2020
- m2r & sphinx>=3.0 are not compatible (more info in pr in progress
  in m2r: miyakogi/m2r#55)
- add path in conf.py to find the nmodl module
- removed various doxygen warnings due to unacceptable keywords
  in configuration files
- adjust checkparent_visitor sphinx autodoc /copybrief
- reduce the maxium number of processors (freezed some workstations)
- mistune downgrade due to conflicts with nbconvert

Co-Authored-By: Omar Awile <[email protected]>
@basnijholt
Copy link

@miyakogi ping. No project that uses m2r builds using the latest Sphinx.
This includes all projects on Readthedocs.io (that use m2r).

@sbliven
Copy link

sbliven commented Jun 29, 2020

@basnijholt You can try @qhua948's fork, published as m2rr.

@CrossNox
Copy link
Author

I've finally released my fork as m2r2 after revamping some of the tooling and building CD and testing pipelines.

@basnijholt
Copy link

Any comments on how https://github.com/qhua948/m2rr and https://github.com/CrossNox/m2r2 differ? Maybe only time will tell us which one will be maintained 😄

orangecms added a commit to orangecms/pslab-documentation that referenced this pull request Aug 9, 2020
Until Sphinx upstream moves to a different markdown converter,
m2r2 would fix builds.
Issue:
sphinx-doc/sphinx#7420
See also:
miyakogi/m2r#55 (comment)
orangecms added a commit to fossasia/pslab-documentation that referenced this pull request Aug 9, 2020
Until Sphinx upstream moves to a different markdown converter,
m2r2 would fix builds.
Issue:
sphinx-doc/sphinx#7420
See also:
miyakogi/m2r#55 (comment)
@axsaucedo
Copy link

axsaucedo commented Aug 28, 2020

This is great, thanks guys, will make a massive difference once it's merged. I'm now using m2r2 and seems to work quite well 👍

@codecov-io
Copy link

Codecov Report

Merging #55 (ee7c818) into dev (66f4a5a) will increase coverage by 0.13%.
The diff coverage is 100.00%.

Impacted file tree graph

@@            Coverage Diff             @@
##              dev      #55      +/-   ##
==========================================
+ Coverage   96.14%   96.27%   +0.13%     
==========================================
  Files           3        3              
  Lines         778      779       +1     
==========================================
+ Hits          748      750       +2     
+ Misses         30       29       -1     
Impacted Files Coverage Δ
m2r.py 93.59% <100.00%> (+0.32%) ⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 66f4a5a...ee7c818. Read the comment docs.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Deprecation Warning: add_source_parser
7 participants