DOC: Minor edits/suggestions from a full runthrough of documentation #121
Conversation
Links were not replacing text with hyperlink in website. Perhaps this was a test-case for other behavior?
Rendered header looks out of place in the web page - alternatively, could provide additional context and keep it in
|
Thank @rossbar I'll work through this. Also be sure to check out the new VS Code extension and let us know any feedback 😁 |
Yeh this is not true (referring to https://spec.commonmark.org/dingus/) and should be changed in the docs. I think @choldgraf added it, so perhaps he could clarify the intended meaning
I can't replicate this; can you specify a certain link to look at.
Yeh fair. the large chunk is there, becuse that is what the performance tests are actually run on (so it has to be 'large'). But I think this can be separated into a separate document and just hid in the documentation (with orphan=True), and linked to in the performance section.
Yeh a seperate issue would probably be best, with a minimal example of what is not working, with a screenshot, of how it currently renders, and explain how you would expect it to render. |
|
Note the circle CI issue is related to pydata/pydata-sphinx-theme#102 (comment) |
|
Ah actually I see the intersphinx issue, is related to referencing the mistletoe docs (which I wrote): https://readthedocs.org/projects/myst-parser/builds/10642528/. Its strange because this build was yesterday, but the last mistletoe build was a week ago: https://readthedocs.org/projects/mistletoe-ebp/builds/ and contains these 'targets' |
|
re: the extra space ( |
|
@choldgraf can you try rerunning the readthedocs ta |
|
done! |
|
Yep that fixed it 👍 |
Sorry, I should've been more specific - glad the RTD rerun fixed it.
If I understood the linked comment (and subsequent discussion) correctly, this should be taken care of in 268dd9e - please make sure that I organized it the way that you prefer though! |
It turns out this is theme/style issue - the |
You just need to also remove requirements.txt from |
yes, I believe that is awaiting pydata/pydata-sphinx-theme#103 |
Updated conf.py and setup.py rtd extras to depend on pydata-sphinx-theme (recent name change). Removed requirements.txt from docs, which only contained a pointer to the repo for pandas_sphinx_theme Updated circleCI and readthedocs configurations to remove doc/requirements.txt
oops - done in a7de620 |
|
Fixes #122 |
This commit implements the move from `mistletoe` to `markdown-it-py`, as the underlying markdown parser. The reason for this is are discussed in executablebooks/meta#44 (comment) and executablebooks/meta#47, and the PR #123 discusses in more details the update. Additional changes: - Update `pydata-sphinx-theme` requirement - Improve testing and move to GitHub Actions CI - Add tests and fixes for reporter warnings and include directive - Add documentation of sphinx parser options - Apply doc fixes suggested by @rossbar in #121 - Add warning for non-consecutive headings
In preparation for another round of converting Elegant Scipy chapters to MyST-flavored markdown, I did a full read-through of the documentation to get caught up on the latest changes/features.
While working my way through the docs (which are really great BTW), I made a couple minor changes mostly of a grammatical nature.
One set of non-grammatical changes that deserve special attention are those in ff7d040. According to the docs, it should be allowed to have a space between bracketed reference links in markdown syntax, i.e.
[name] [key]is equally as valid as[name][key]; however, this does not appear to work as expected (or at least not according to my interpretation of the docs). I've never used that syntax with markdown before, so I don't know if this is a MyST issue or a documentation issue - I just thought I'd draw extra attention to it.In addition to the changes, I had a few comments additional comments:
using/syntax.mddon't appear to have worked on the deployed docs. They work when building locally though, so maybe the version deployed to readthedocs needs to be updated.using/benchmark.mdcould maybe be titled differently or split into two separate pages. There is a brief section at the top of the page that discusses benchmarking/performance, followed by a much longer chunk of unrelated-ish text presenting an overview of markdown. From an organizational standpoint it might be nice to have an "Overview of markdown" page and a separate "Performance" page.