Ability to add usage samples to API reviews #285
Comments
|
cc: @terrajobst, @pakrym |
|
This would indeed be very useful! |
kurtzeborn
added
the
Central-EngSys
praveenkuttappan
added
the
feature-request
|
I think we should increase the priority of this work item. Reviewing usage samples is a part of our process, yet we don't have a structured way to submit them, comment on them, and manage them. |
|
I agree. It would be nice to have a separate 'code samples' tab in each APIView, perhaps, that would allow the user to supply markdown formatted text, in the same way that today they might write a gist. It brings the samples far closer to the API. |
|
A single markdown document might be sufficient for a start. The trick will be to figure out commenting in the end result. |
|
I was discussing this with @praveenkuttappan as I have a group of student engineers working with me who may implement it. My current thinking of how this will work is the following:
The trade-off with this approach is that we will not be able to do line-by-line feedback of the usage samples, but it makes implementation drastically simpler. I'm keen to hear thoughts on trade-offs - would you rather the functionality I describe above existing ~soon, or would you rather have line-by-line commentary of the usage samples / other documentation? Thoughts? // @KrzysztofCwalina |
|
I'll start working on this now @JonathanGiles |
…nput, and remove samples.
|
@praveenkuttappan Can you please help me add https://github.com/xoofx/markdig as a dependency for the MD parsing in this issue? |
Is there a released package from this repo? I prefer not to take a dependency on source which is very likely to cause a breakage when developer makes any breaking change in their repo. |
That makes sense. There is a NuGet package of the repo available here: https://www.nuget.org/packages/Markdig/ |
|
Yes. Absolutely. So this link should help you add it as dependency to APIViewWeb project. manage nuget package |
|
@praveenkuttappan Additionally, do you have a preference for where comments are stored? Currently the options I can think of are:
|
Let me check the error with markdig and I will get back to you. And regarding sample comments: |
I have found that APIViewWeb is already using MarkDig.Signed that was causing conflict when you tried to add Markdig dependency. I have submitted a PR to update Markdig.signed version to latest. We don't need Markdig. MArkdig.Signed is what we should use, and it's already linked to APIViewWeb project. Please let me know if you are not able to get any specific feature. Ideally Markdig.Signed should have all features supported by MArkdig. It's just a signed nuget package. That's all. Here is my PR to update version: #3914 |
|
@praveenkuttappan I believe I misspoke initially, I am not adding Markdig itself as a dependency, but a new item, specifically "Markdig.SyntaxHighlighting". When this is added, VS/Nuget provide their own Markdig version, since it does not see Markdig.Signed as an appropriate dependency. This is where the errors occur. I am not worried about the specific SyntaxHighlighting package I use, but I would appreciate help in getting at least one of them working with Markdig.Signed as opposed to Markdig. (Markdig.Signed does have everything, and is what I am using for the core of the project, but as Syntax Highlighting was requested also, I am working to include it.) |
I see the issue now. Thanks for the clarification. This can be resolved if we remove
|
…or dependencies in Azure#285
author Baas-hub <benjbaas@gmail.com> 1659925517 +1200 committer Chidozie Ononiwu <chononiw@microsoft.com> 1663964726 -0700 parent 2d7456e author Baas-hub <benjbaas@gmail.com> 1659925517 +1200 committer Chidozie Ononiwu <chononiw@microsoft.com> 1663964615 -0700 Adding Usage Sample page and Models for Azure#285 Continued advancements on adding usage samples. Milestone step for Azure#285: Capability to upload via file or text input, and remove samples. Minor refactor and tidy of backend code. Adding Markdown to HTML parsing for display Comments in bugged state. Going to experiment with new method of construction that may make them easier to manage. Inline comments semi-working Updated CONTRIBUTING.md and altered styling minimally. Syntax highlighting added for Azure#285 Added editable samples Added revisions to samples Minor finalizing changes Remvoing suggested inputs from revision labels Requested changes Changing wording as suggested Revert "Remvoing suggested inputs from revision labels" This reverts commit 0b96946. Undoing bad push Sandboxing changes: create apireview gen pipeline (Azure#3347) * APIView sandboxing pipeline yaml to generate api review file Bump Azure.Storage.Blobs (Azure#3750) Bumps [Azure.Storage.Blobs](https://github.com/Azure/azure-sdk-for-net) from 12.8.0 to 12.13.0. - [Release notes](https://github.com/Azure/azure-sdk-for-net/releases) - [Commits](Azure/azure-sdk-for-net@Azure.Storage.Blobs_12.8.0...Azure.Storage.Blobs_12.13.0) --- updated-dependencies: - dependency-name: Azure.Storage.Blobs dependency-type: direct:production ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Bump Azure.Storage.Blobs (Azure#3749) Bumps [Azure.Storage.Blobs](https://github.com/Azure/azure-sdk-for-net) from 12.8.0 to 12.13.0. - [Release notes](https://github.com/Azure/azure-sdk-for-net/releases) - [Commits](Azure/azure-sdk-for-net@Azure.Storage.Blobs_12.8.0...Azure.Storage.Blobs_12.13.0) --- updated-dependencies: - dependency-name: Azure.Storage.Blobs dependency-type: direct:production ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Bump Azure.Storage.Blobs in /src/dotnet/APIView/APIViewTest (Azure#3732) Bumps [Azure.Storage.Blobs](https://github.com/Azure/azure-sdk-for-net) from 12.0.0 to 12.13.0. Bump MacOs version to macos-11 (Azure#3753) Resolve Azure#3715 Tracking issue: actions/runner-images#5583 Introduced codeowner-extractor. (Azure#3719) * Introduced codeowner-extractor. * Refactor using implicit principal and vault based config (Azure#3751) * Refactor using implicit principal and vault based config * Cleanup logging and skipping logic in Processor. Use bulk github user mapping api. * Avoid using arrays with IConfiguration * Improve logging in GitHubToAADConverter and pipeline owner extractor Co-authored-by: Nicholi Harris <t-nharris@microsoft.com> Co-authored-by: Patrick Hallisey <pahallis@microsoft.com> Set net core version for pipeline-owners-extractor (Azure#3771) APIVIew - Make GitHub token optional (Azure#3757) * Make github token optional when testing locally Update sandboxing pipeline to send request to APIView (Azure#3775) * Update sandboxing pipeline to send request to APIView Revert Accidentally Broken Sample assets (Azure#3776) * reverting assets.json to ensure tests continue succeeding Update nuget dependencies for pipeline witness (Azure#3745) Return 401 error code if org info is not available for PR owner (Azure#3778) * Return 401 error code if org info is not available for PR owner [Perf] Display results with 4 significant figures (Azure#3770) - Fixes Azure#3554 Remove build log queue based fanout (Azure#3789) Add pipeline-owners-extraction pipeline (Azure#3784) * Add pipeline-owners-extraction pipeline Fix misleading step name in az module install (Azure#3787) The name of this step is misleading and needed renaming. Server changes to create manual and upgrade required API reviews using pipeline(sandboxing) (Azure#3774) * Generate reviews using sandboxing pipeline docs: add disclaimer and specificity (Azure#3796) Co-authored-by: Dohyun Kim <tnghwk0661@gmail.com> Co-authored-by: Jeesang Kim <jeenowden@gmail.com> Co-authored-by: Dohyun Kim <tnghwk0661@gmail.com> Co-authored-by: Jeesang Kim <jeenowden@gmail.com> Add code owner processing to PipelineWitness (Azure#3742) Add kusto schema for tables and views (Azure#3425) Add Option for Hiding Left Navigation (Azure#3686) * Add option for hiding left navigation * Improve reviews page command bar * Persist page settings as user preferences * Smart update cache * Add auto mapper for mapping between models Fix issue when uploading json file to APIView (Azure#3800) Feature/3465 support for java variants (Azure#3797) Added Variant field to reviews and codefiles for different language variants Improving Java reference docs in apiview Fix label case in review dropdown (Azure#3814) Fix bad path to sample matrix json (Azure#3765) [perf] Right-align numerical values in tables (Azure#3802) - Change percentages from two to one decimal place, since our results are not stable enough to justify two decimals - Update sample results to 4 significant figures - Fixes Azure#3703 Fetch all reviews when running background tasks (Azure#3818) Feature/import warnings (Azure#3648) * update class names * docs * tests * fixme * change to convention * only allow imports from transport * spacing * naming * better naming * typo in tests * update linter names * fix test (please) * better class name Create API review using modules in consistent order (Azure#3832) * Create API review using modules in consistent order Update Python parser version and Python version to match version used by CI (Azure#3833) Add link checking for stress CI (Azure#3826) * Add link checking for stress CI * Remove region segment from stress testing links Add `RegexEntrySanitizer` (Azure#3807) * add RegexEntrySanitizer and accompanying tests * Update tools/test-proxy/Azure.Sdk.Tools.TestProxy/Sanitizers/RegexEntrySanitizer.cs Fix example group (Azure#3845) * fix: reuse m4 operation group to group examples * build: release @autorest/testmodeler_v2.3.1 [Pylint] adding in TypeError to exception for next() if type cant be inferred (Azure#3843) * adding in TypeError to exception for next() if type cant be inferred * update version * fix paging test * pass -> return so that on exceptions we dont throw a warning * fixing merge conflict * spacing: * spacing Bump Azure.Storage.Blobs (Azure#3729) Bumps [Azure.Storage.Blobs](https://github.com/Azure/azure-sdk-for-net) from 12.6.0 to 12.13.0. - [Release notes](https://github.com/Azure/azure-sdk-for-net/releases) - [Commits](Azure/azure-sdk-for-net@Azure.Storage.Blobs_12.6.0...Azure.Storage.Blobs_12.13.0) --- updated-dependencies: - dependency-name: Azure.Storage.Blobs dependency-type: direct:production ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Updating Proxy Dev Cert (Azure#3860) support creating go apiview in pipeline (Azure#3878) * support creating go apiview in pipeline * format Vendor CrossPlat PemReader from azure-core (Azure#3882) * standardize line endings for RecordingHandler.cs. Update pem to an expired certificate that should be valid crossplat. remove trial RemoveOnLinuxFact * use vendored internal-only azure-core classes for loading a X509Certificate2 from the TLS Certificate input string. [check-enforcer] Remove unused dependency Azure.Storage.Blobs (Azure#3890) [Python APIView] Add error diagnostic if pylint parsing fails rather than fail APIView (and thus CI) (Azure#3884) * Make pylint parsing failure create an APIView error instead of failing the tool (and thus CI). * Closes Azure#3842. Update CODEOWNERS (Azure#3891) - Remove previous owners - Sort tools dirs alphabetically - Add owners for perf-automation and CODEOWNERS new pipeline for codegen (Azure#3375) * new pipeline for codegen * bugfix: taskresult is required, check exist before prepare sourcecode * Simplify Judgment Conditions * delete unnecessary variable * separate artifacts from total one to three part * move mkdir out of loop for it has the same path * may not generate artifact so event task failed, the pipeline should continue next task * use pr number to checkout swagger repo * [bugfix] fix missed parameter * delete test code * pipeline support use swagger pr to checkout spec repo * try upload logs file to artifact even sdk generation failed * debug for pipeline * build dpg * codegen pipeline support java dpg * add release pipeline name and build type in result * use azure-sdk account for create sdk pr * support add ex cmd for docker * event generate and build stage failed, try to upload source code and artifact * don't exit 1 event generate cmd return 1 * use one token for all git cmd * set sdk url by variable * use env variable to control whether to show debug info * remove hard code branch * roll back for debug * test * set basedir for git wapper * lint fix * update js ci test repo commitid * lint fix Update docs/trusting-cert-per-language for Mac troubleshooting (Azure#3739) * update docs/trusting-cert-per-language for Mac troubleshooting * fix images under the _images folder Co-authored-by: ponopono0322 <ponopono0322@gmail.com> [Test-Proxy] Add Optional Specificity to the TLSValidationCert (Azure#3894) * add optional specificity to the hostname [Python APIView] Fix issue with duplicated diagnostics (Azure#3908) * Troubleshoot issue * Bump pylint-guidelines-checker version. * Fixes Azure#3712. Update CHANGELOG.md (Azure#3921) updated targeted proxy version to one that properly allows consumption of TLS certificates (Azure#3945) docker manifest deployment honors stabletags option (Azure#3913) Remove duplicate PR API review revisions (Azure#3949) * Remove duplicate pull request API review revisions Improvements around aliased types (Azure#3940) * Improvements around aliased types Issue a diagnostic error if an exported, aliased type contains nested types that aren't exported from the same package. Include methods for aliased types in the source package. Removed references to ioutil as it's been deprecated. * skip unexported fields * handle arrays * fix happy line * little more refinement * refine per feedback * array with pointer-to-type * add tests Sync azure-dev (Azure#3931) [Perf] Update storage GA package versions (Azure#3959) Feature/3810 replace language image references with css (Azure#3876) Replace language icon conditionals with CSS classes with background-image fix bug: miss autorest command in _meta (Azure#3966) Co-authored-by: Wei Dong <weidong@microsoft.com> upgrade version (Azure#3967) Co-authored-by: Wei Dong <weidong@microsoft.com> Explicit Error Message for Mismatch BEGIN and END Aliases (Azure#3889) Explicit Error Message for Mismatch BEGIN and END Aliases Fix issue with read-only properties. (Azure#3961) Add dark theme for APIView (Azure#3747) * Add dark theme for APIView * Add button for switching themes * persist Dark Theme * Allow Updates to UserPreference on all Pages * Handle cases where preference model is null * Fix colors for popover codesnippet-maven-plugin Performance Improvements (Azure#3970) Pipeline to covert manual JS reviews to code file (Azure#3897) add admin label to scheduler project (Azure#3974) eng-common sync is running on hosted pools (Azure#3863) Fix codesnippet-maven-plugin Bug with Full Class Codesnippets (Azure#3979) js apiview parser build pipeline (Azure#3847) * Pipeline yaml to build and publish JS APIView parser Block non-abstract transport imports (Azure#3930) * block transport imports * use separate rule * register linter * styling * fix comments * readme * typos Removes excess newlines Updating page to work with other changes (Azure Azure#285) Adding comment note for suppression reasoning. Suppressing warnings for dependencies in Azure#285 Changing "sample" to "revision" to account for new revision system add option --explicit-types to allow customize tagged types in exported code model. (Azure#3976) * explicti-types * changelog * lint * fix-swaggerpath * fix * use operation response schema * changelog * publish Only skip /internal sub-directories (Azure#3993) Allows support for the poorly named "internal" module. [Perf] Update EventHubs package versions (Azure#3995) clone sdk repo in grow up scenario (Azure#3667) * save * clone sdk repo in grow up scenario * lint fix * doc fix * clone spec repo in grow up * add skip-generation param in rerunning task * update doc * mute output * add new param --is-public-repo * lint * result change * fix test Co-authored-by: Wei Dong <weidong@microsoft.com> Remove Duplicate Event Listener Code (Azure#3987) * Remove duplicate event listener code * Ensure that js files are not cached Initial integration tests (Azure#3932) * Initial integration test * Add Restore Tests * Update TODO in GitProcessHandler Update stress readme to remove misleading sections (Azure#4003) [Perf] Add pipeline to validate changes to perf-automation (Azure#3874) - Fixes Azure#3559 stress status dashboard update (Azure#3998) * stress status dashboard update * Adding back log analytics in stress dashboard * delete comment Add integration reset tests (Azure#4013) * Add integration reset tests * Updates based upon feedback Hiding warning for ColorCode inclusion Removing unused variable causing build failure Reduce throttling by adding distributed locks (Azure#3973) * Add async locks * Add cosmos initialization and secrets resolution * Increate queue worker count in prod to 10 per instance Support language-specific CSS files Azure#3464 (Azure#3978) Support language-specific CSS files Co-authored-by: Jonathan Giles <jonathan.giles@microsoft.com> Adding Solarized Dark theme (Azure#4005) * Tweaking error/warning banner colors * Minor adjustments to style based on fast pass feedback Adding missed comma Feature/2389 show reference docs for specific method class (Azure#3941) Reference doc code folding feature - fully implemented Adding Java-Specific typekinds Azure#3463 (Azure#3988) Adding accomodation for new features Adding authorization, Modifying to soft deletes, Tidying unused code, and refactoring backend systems for revisions Remove a few extra properties Bugfixing deleting last revision not properly deleting, updating styles Cleaner error handling for blob/container misconfiguration Adding usage samples comments to conversation page Adding icons to usage sample buttons Updating for feedback. (Remove excess check and fix indentation) Removing old code and implementing feedback
…nput, and remove samples.
…or dependencies in Azure#285
…nput, and remove samples.
…or dependencies in Azure#285
* Adding Usage Sample page and Models for #285 * Continued advancements on adding usage samples. * Milestone step for #285: Capability to upload via file or text input, and remove samples. * Minor refactor and tidy of backend code. * Adding Markdown to HTML parsing for display * Comments in bugged state. Going to experiment with new method of construction that may make them easier to manage. * Inline comments semi-working * Updated CONTRIBUTING.md and altered styling minimally. * Syntax highlighting added for #285 * Added editable samples * Added revisions to samples * Minor finalizing changes * Remvoing suggested inputs from revision labels * Requested changes * Revert "Remvoing suggested inputs from revision labels" This reverts commit 0b96946. Undoing bad push * Removes excess newlines * Updating page to work with other changes (Azure #285) * Adding comment note for suppression reasoning. Suppressing warnings for dependencies in #285 * Changing "sample" to "revision" to account for new revision system * Hiding warning for ColorCode inclusion * Removing unused variable causing build failure * Adding accomodation for new features * Adding authorization, Modifying to soft deletes, Tidying unused code, and refactoring backend systems for revisions * Remove a few extra properties * Bugfixing deleting last revision not properly deleting, updating styles * Cleaner error handling for blob/container misconfiguration * Adding usage samples comments to conversation page * Adding icons to usage sample buttons * Updating for feedback. (Remove excess check and fix indentation) * Removing old code and implementing feedback Co-authored-by: Baas-hub <benjbaas@gmail.com>
It would be great if usage sample, and other commentary, could be added to API review packets. This would make the tool into a one stop shop.
I can imagine the following experience:
Fancy features:
The text was updated successfully, but these errors were encountered: