Add docs/ folder and an intro tutorial #958
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
Codecov Report
@@ Coverage Diff @@
## master #958 +/- ##
==========================================
- Coverage 98.73% 98.62% -0.12%
==========================================
Files 32 38 +6
Lines 1428 1529 +101
==========================================
+ Hits 1410 1508 +98
- Misses 13 15 +2
- Partials 5 6 +1
📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
abhinav
force-pushed
the
abg/tutorial
branch
2 times, most recently
from
5586d78 to
bf33fa2
Compare
This adds a new docs/ folder to the Fx repository. This is where non-API-reference documentation will reside. To set things up, this adds a docs/CONTRIBUTING.md with guidance on how to contribute to the Fx documentation. It includes tooling to ensure that code snippets inside documentation remain up to date. To do that, this relies on two tools: - mdox does the bulk of the heavy lifting here - the region shell script helps pick out named snippets of code from a flie
abhinav
force-pushed
the
abg/tutorial
branch
2 times, most recently
from
f10683f to
0a63915
Compare
|
Looks like we can't have the doc tests run on Windows. |
|
Note that the only failure here is that parts of the code added in the patch are not covered. |
This adds a "Getting started with Fx" tutorial. The tutorial is intended to be a simple step-by-step with minimal explanations that a user can follow along to. At the end of the tutorial, they'll have encountered: - basic dependency injection - named values - value groups
This rewords the introduction in the readme to better state the benefits of using Fx, and links to the get-started tutorial to help users get started. Part of this is to add the root README to the list of files processed by mdox, as a result of which some of the links are also rewritten. (mdox prefers inline links, not reference style links, and there's no way to change that right now.)
This adds tests for all get-started code samples. Since can't get coverage for these tests because they rely on os/exec to create subprocesses, also exclude these tests from codecov's coverage tracking.
The example test is flaky because `go ListenAndServe()` is not always ready to accept connections by the time we get to making the request. To fix this, start a listener explicitly in a blocking manner, and run the Serve goroutine separately.
sywhang
approved these changes
Oct 12, 2022
Merged
abhinav
added a commit
that referenced
this pull request
Oct 12, 2022
This migrates docs added in #958 into a GitHub Pages website powered by Vuepress (same as https://cadenceworkflow.io/). Besides the boilerplate, this carries the content over almost as-is. One change we've made here is to split the many sections of the getting started tutorial into different pages. This helps keep the length of the document manageable, and makes the transition between each step more obvious.
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.
This adds a new docs/ folder to the repository.
We'll put non-API-reference documentation in this folder.
To begin with, this folder contains the following documentation:
(please read before adding documentation)
In the interest of keeping the documentation up-to-date and valid,
we make use of mdox to:
Further, to ensure that all the code samples are runnable,
this includes tests for all example code.
Testing the example code is a bit complex because we
need to treat it like an application "from outside"
so all tests rely on TestMain-style hijacking to run the programs.
Rendered documentation: