Port CHANGELOG.md -> CHANGELOG.rst #254
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ErlendHaa
force-pushed
the
port-changelog-to-rst
branch
2 times, most recently
from
b9f7018 to
2977525
Compare
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
These properties were documented first in the class-docstring under the section Attributes, and then again with a property docstring. According to the numpy styleguide [1] which we try to follow, this is good practice. However, it turns out that prior to sphinx v3.0.0 these are rendered twice, and from v3.0.0 an warning is issued. We deliberately fail out CI-pipeline on any warnings, hence we caught this now. [1] https://numpydoc.readthedocs.io/en/latest/format.html#class-docstring
ErlendHaa
force-pushed
the
port-changelog-to-rst
branch
2 times, most recently
from
7853214 to
82b1ee7
Compare
achaikou
approved these changes
Apr 20, 2020
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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