Gatsby: Python packages source, intersphinx source #269
Conversation
This file contains hidden or 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
for rst in **/*.rst; do pandoc "$rst" -f rst -t gfm -o "${rst%.*}.md"; done
poetry remove --dev doc8 alagitpull docutils sphinx-issues sphinx
poetry add mkapi --dev --python ">=3.7" -E docs
poetry add mkdocs --dev --python ">=3.5" -E docs poetry add mkdocs-material --dev --python ">=3.5" -E docs
poetry add sphinx-issues --dev --extras docs --optional poetry add alagitpull --dev --extras docs --optional --allow-prereleases
…numpy format (#267) - Move sphinx format to Numpy-style - Move from reStructuredText to Markdown (via recommonmark). The master plan is to eliminate docutils and sphinx as a bottleneck completely in favor of something else (e.g. gatsby with a source that inspects our modules and can source intersphinx) - Move from RTD to GitHub Action, full support of poetry extras packages, deploys straight to S3 and CloudFront
Codecov Report
@@ Coverage Diff @@
## master #269 +/- ##
==========================================
- Coverage 85.57% 84.84% -0.73%
==========================================
Files 16 16
Lines 804 805 +1
==========================================
- Hits 688 683 -5
- Misses 116 122 +6
Continue to review full report at Codecov.
|
tony
force-pushed
the
master
branch
3 times, most recently
from
5354b23 to
effff43
Compare
tony
force-pushed
the
master
branch
4 times, most recently
from
cf9f3ef to
410e041
Compare
tony
force-pushed
the
master
branch
2 times, most recently
from
7f69eab to
c480bb4
Compare
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.
Eliminate dependency on docutils and sphinx. These are great projects, but they not friendly
to configure on and focused primarily toward internal code API documentation.
Today - markdown is more commonplace and supports extensions better than docutils does
and static site generators offer better inter-document linking than sphinx. For instance, gatsby
supports intuitive, structured, comprehensive, detailed, typed and recursive sources in graphql,
rather than the visitor pattern offered by docutils.
mkdocs, pdoc(3), and even non python documentation generators have a legitimate stakehold
in making documentation portable.
Other sphinx projects (e.g. flask, standard library python) can still be linked to intersphinx
Python package source
https://github.com/readthedocs/sphinx-autoapi + https://github.com/PyCQA/astroid
Generate gatsby source by parsing a package into a JSON / YAML structure
then into GraphQL
Intersphinx source
https://sphobjinv.readthedocs.io/en/latest/index.html
Parse objects.inv on projects into gatsby graphql source
MDX utilities to link to intersphinx sources
MDX utilities to link to python package sources