docs: setup mkdocs #414
Merged
docs: setup mkdocs #414
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
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
45d9bff to
0fba707
Compare
JP-Ellis
had a problem deploying
to
github-pages
GitHub Actions
Failure
|
Hey hey, So we sync files from repos to the main docs site Pact pythons sync job is here https://github.com/pact-foundation/docs.pact.io/blob/master/scripts/sync/pact_python.rb Its pretty easy to update the format on the site to make a readme split out into different sections, and if this creates html, we can render that on the doc site too. I'm open to any reimagined ideas about the docs, I want to make things easier for devs in their native languages but also want a unified experience for all users so they can see how to do the same Pact thing, across every language in a meaningful way. I like the idea of correct api documentation that is generated from the code, the code is our source of truth, and I like things like rusts docs for a quick google or searching functions, its consistent across that ecosystem. Curious to see what it looks like when you get the deployment sorted, or a preview hooked up |
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
0fba707 to
d555b56
Compare
JP-Ellis
had a problem deploying
to
github-pages
GitHub Actions
Failure
JP-Ellis
added
difficulty:medium
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
d555b56 to
afa1972
Compare
JP-Ellis
had a problem deploying
to
github-pages
GitHub Actions
Failure
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
afa1972 to
41756ce
Compare
JP-Ellis
had a problem deploying
to
github-pages
GitHub Actions
Failure
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
41756ce to
b4e06e2
Compare
JP-Ellis
had a problem deploying
to
github-pages
GitHub Actions
Failure
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
b4e06e2 to
15a5506
Compare
JP-Ellis
had a problem deploying
to
github-pages
GitHub Actions
Failure
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
15a5506 to
d0bd1a7
Compare
JP-Ellis
had a problem deploying
to
github-pages
GitHub Actions
Failure
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
d0bd1a7 to
b3420e9
Compare
JP-Ellis
had a problem deploying
to
github-pages
GitHub Actions
Failure
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
b3420e9 to
84abad6
Compare
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
84abad6 to
67f83d7
Compare
Closed
|
The work is finally ready for review, and can be viewed online at: Important Before this PR is merged, the publication step of the Docs GitHub Action must be modified so that it only runs on @YOU54F and @mefellows, I would be keen for your review on the docs before it gets merged as this is a rather substantial change, and I want to make sure there are no unforeseen repercussions. |
MkDocs is a popular tool in the Python ecosystem to generate documentation. It has support for parsing Python docstrings in order to generate API documentation quite easily. Signed-off-by: JP-Ellis <josh@jpellis.me>
Signed-off-by: JP-Ellis <josh@jpellis.me>
The emoji extensions have been incorporated directly into mkdocs-material. Signed-off-by: JP-Ellis <josh@jpellis.me>
The scripts are significantly improved to make them easier to use and maintain. Signed-off-by: JP-Ellis <josh@jpellis.me>
Signed-off-by: JP-Ellis <josh@jpellis.me>
Signed-off-by: JP-Ellis <josh@jpellis.me>
Signed-off-by: JP-Ellis <josh@jpellis.me>
The main README has been completely overhauled: - It is now more closely aligned with Pact JS and Pact Go - It is much shorter, with usage documentation having been moved into `/docs` - Reference to Pact Python `v3` has been added. Signed-off-by: JP-Ellis <josh@jpellis.me>
Signed-off-by: JP-Ellis <josh@jpellis.me>
This is a major write up of docs for V3. Including the following changes: - Adding a timeline to make it clearly visible - Added usage documentation within the modules - Consolidated all `Interaction` classes into one module, and hiding the sub-modules from the docs. Signed-off-by: JP-Ellis <josh@jpellis.me>
Signed-off-by: JP-Ellis <josh@jpellis.me>
Signed-off-by: JP-Ellis <josh@jpellis.me>
Fix typos Authored-By: JosephBJoyce Cherry-Picked-By: JP-Ellis <josh@jpellis.me>
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
d9c1f08 to
1695527
Compare
Due to the processing that is done on files outside of `docs/`, links to file _inside_ the `docs/` directory do not work. This adds a hook to MkDocs which rewrites these links. Signed-off-by: JP-Ellis <josh@jpellis.me>
JP-Ellis
force-pushed
the
docs/initial-mkdocs
branch
from
1695527 to
02ec225
Compare
Specifically, adding `FORCE_COLOR` to ensure we have coloured output (it is prettier afterall), and making sure `HATCH_VERBOSE` is always enabled in case there's an error. Signed-off-by: JP-Ellis <josh@jpellis.me>
Signed-off-by: JP-Ellis <josh@jpellis.me>
|
Closes #416 |
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.
📝 Summary
MkDocs is a popular tool in the Python ecosystem to generate documentation. It has support for parsing Python docstrings in order to generate API documentation quite easily.
The docs can be seen live at:
Note that a lot of the 'legacy' codebase will not render correctly. The sections which should be looked at are:
pact.v3Important
Before this PR is merged, the publication step of the Docs GitHub Action must be modified so that it only runs on
master.🚨 Breaking Changes🔥 Motivation
Work for this was created during my own development to see the API from an end-users' perspective.
🔨 Test Plan
🔗 Related issues/PRs