Add manual changelog to documentation

[tsalo]

Closes #603. This isn't an automated solution, but it does give me the control I need to add things like warnings to old versions.

Changes proposed in this pull request:

• Add docs/changelog.rst.
• Include the new file in docs/index.rst.

[codecov]

Codecov Report

Merging #635 (3bdd8d9) into main (d37c216) will decrease coverage by 0.03%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #635      +/-   ##
==========================================
- Coverage   85.32%   85.28%   -0.04%     
==========================================
  Files          41       41              
  Lines        4503     4507       +4     
==========================================
+ Hits         3842     3844       +2     
- Misses        661      663       +2     

Impacted Files	Coverage Δ
nimare/decode/discrete.py	92.34% <0.00%> (-4.27%)	⬇️
nimare/meta/cbma/mkda.py	97.09% <0.00%> (ø)
nimare/correct.py	94.28% <0.00%> (+1.21%)	⬆️
nimare/stats.py	98.97% <0.00%> (+4.74%)	⬆️

---

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 d37c216...3bdd8d9. Read the comment docs.

[tsalo]

@JulioAPeraza I'm only now realizing that using MarkDown for the changelog really limits it. The main thing I'd like to have is admonitions for version-specific warnings (e.g., don't use ALESubtraction in version 0.0.8). Is there any way to use RST for the release notes and/or changelog?

[JulioAPeraza]

I think the Github Action I am using only export to .md format. It takes the release tag and body text and writes it in the CHANGELOG.md. We can try adding an additional step to this action to convert from md to rst or try with a different Github Action that export to rst (https://github.com/marketplace/actions/changelog-ci).
Is this the warning we should have documented: https://nimare--635.org.readthedocs.build/en/635/changelog.html#id14 ?
I think if the warnings are not part of the release note, they will need to be added manually.

[tsalo]

Okay, thanks for the clarification. I can just use bolded text or something. It's probably not worth it to try to convert the Markdown to RST if it's not just a simple setting.

Is this the warning we should have documented: https://nimare--635.org.readthedocs.build/en/635/changelog.html#id14 ?

The fix is documented in the ALESubtraction docstring, I believe.

I think if the warnings are not part of the release note, they will need to be added manually.

Yes, we will generally only know about version-specific problems after the releases have been made, so we will add those notes manually.

EDIT: The good news is that it looks like the RST admonitions render properly in the Sphinx-built docs, so it's not a big deal. The only place where the admonitions won't render is looking directly at the Markdown file.

[tsalo]

@JulioAPeraza Can you take a look at the proposed changelog format and see how it will compare to the automatic one you added?

[JulioAPeraza]

I was looking at other projects that use this action and the only difference will be in the date of the release. They use 0.0.12rc3 - 2022-03-21 instead of 0.0.12rc3 (2022-03-21), everything else will look like the release note.

[tsalo]

I'm glad the date is in there at least. I'll change the format for the manually-created ones to match the new format.

[JulioAPeraza]

Should these headings include blank lines before and after?

[tsalo]

I copied them from the release notes, so I think the problem is in the template.
However, I think the rendered changelog looks okay, so I don't know if it's an issue.

[JulioAPeraza]

I noticed the issue in the previous docs build. I only see the first heading ### 🛠Breaking Changes, the other ones (### 🎉 Exciting New Features, ### 🐛 Bug Fixes, and ### Other Changes) are mixed in the text.
If that is the case, it may be an issue for the automatic changelog, since it will copy the body of the release notes as it is (without blank lines between ### headings).

[tsalo]

Ohhh... nice catch. I completely missed that.

[tsalo]

I don't know how to fix this though... the template doesn't seem to let us control spacing.

[tsalo]

Hopefully the auto-generated version will look okay. I'll merge this once CI passes and then I'll make a release (0.0.12rc4 😬).