[GSOD]Adds new quickstart doc #1718
Conversation
|
This is a great start. I had some minor comments, and I want to note that I didn't actually try to follow the guide yet to confirm it works as expected (and that should be done by someone besides @HCloward prior to merging). |
There was a problem hiding this comment.
I left some comments and suggestions, mainly around phrasing and formatting. (For some reason, I don't have the permission to batch-commit my own suggestions, so I apologize for inconveniencing you @HCloward).
Overall, this looks really good 👍 The instructions are pretty clear and seem easy to follow! I am going to actually test these instructions and report back with more feedback.
In the meantime, I've got one idea that we can discuss. I would love this quickstart to have some kind of a "head"
Or maybe to simplify it even more, and reduce the amount of clicks/navigation the users would have to go through - we could put all the quickstart content on one page? I'm not sure which approach would be better, so I'd love to hear from @swapnilogale too.
|
Oh, and to answer your question from the PR:
Not yet, so I think you can just skip that part of the PR template in the future. :) |
I agree an introduction is needed and will add one. I think it would be best to separate the pages bc otherwise it is overwhelming and I think it is good to keep it simple for the user. |
Co-authored-by: Ivana Isadora Devcic <33730345+skadinna@users.noreply.github.com>
|
I love the intro. Great improvements! 🎉 |
I don't mind having separate pages - easier to search for something :) |
There was a problem hiding this comment.
Looks great @HCloward - @skadinna has picked up most of the style and formatting - I just spotted a small typo
There was a problem hiding this comment.
Really great work, @HCloward 👍 I like the intro page a lot! I think you just have a couple of minor things to fix here, and then this should be good to go.
Yeah, I'm OK with separate pages now that we have an intro page that binds them all together :) |
* feat: add new option hideSchemaPattern (Redocly#1475) * feat: add new option hideSchemaPattern * chore: add hideSchemaPattern option to readme * fix: add missed labels to elements (Redocly#1445) * chore: upgrade prism.js fixes Redocly#1455 * chore: Release 2.0.0-rc.48 🔖 * docs: fix `menuToggle` default value fixes Redocly#1476 [ci skip] * docs: fix the Rebilly link * chore(cli): v0.10.2 * fix: fix SourceCodeWithCopy component to be non-pure * docs: document theme options (Redocly#1438) * chore: remove duplicate semicolons (Redocly#1504) * fix: crash on multiple examples on parameter object fixes Redocly#1485 * fix: pass boolean and number values as a string in highlight function (Redocly#1512) * chore: Release 2.0.0-rc.49 🔖 * chore: update travis badge url * fix: background-color in search results (Redocly#1531) * fix: background-color in search results * Delete some changes * chore: clean up .travis.yaml * chore(cli): upgrade redoc to rc.49 * chore(cli): v0.10.3 * fix: false-positive recursive tag case when using oneOf + allOf (Redocly#1534) * fix: add includes polyfill fixes Redocly#1530 * chore: Release 2.0.0-rc.50 🔖 * chore(cli): v0.10.4 * docs: remove outdated config option from readme (Redocly#1543) * docs: minor syntax highlight fix on the README (Redocly#1549) * feat: add disable-google-font parameter to serve command in cli (Redocly#1558) * docs: remove extra word in grammar (Redocly#1539) * chore: use openapi-core to bundle definition instead of json-schema-ref-parser (Redocly#1500) * chore: use openapi-core to bundle definition instead of json-schema-ref-parser * chore: update: root and demo webpack configs * chore: refactor loadAndBundleSpec * chore: update vesions: openapi-core, redoc * chore: rolled back webpack.config(s) to previous version * chore: changed the way of creating core Config for bundling definition * fix: disable eslint react/display-name * fix: update nodejs version to 12 in travis config * chore: optimize verification: browser or server * chore: add fetch only for browser * Update src/utils/loadAndBundleSpec.ts * chore: isBrowser verification improvment Co-authored-by: Roman Hotsiy <gotsijroman@gmail.com> * chore: unit tests to check loading and bundling api definitions with openapi-core (Redocly#1568) * chore: Release 2.0.0-rc.51 * chore(cli): v0.11.0 * chore(cli): v0.11.1 * fix: broken paths when budle or serve using cli (Redocly#1572) * chore(cli): v0.11.2 * chore: update openapi-core version to fix parsing root document * chore: Release 2.0.0-rc.52 * chore: Release 2.0.0-rc.53 * fix: added missing semicolon to styling (Redocly#1578) * docs: update specUrl (Redocly#1577) * chore(cli): v0.11.3 * fix: right absolute path for load and bundle definition (Redocly#1579) * chore(cli): v0.11.4 * chore: update(cli) engine node version >=12 (Redocly#1583) * fix: parse json theme string for standalone tag (Redocly#1492) * fix: use operation path if operation summary/description is not provided (Redocly#1596) resolves Redocly#1270 * feat: add basic support openApi 3.1 (Redocly#1622) * chore: upgrade dependencies (Redocly#1634) * chore: modernize build pipeline (Redocly#1635) * chore: remove extra webpack resolver * feat: merge refs oas 3.1 (Redocly#1640) * chore: v2.0.0-rc.54 * chore(cli): upgrade redoc to rc.54 * chore(cli): v0.12.0 * chore(cli): v0.12.1 * feat: added git folder sync config * chore: change cors url in the demo * fix: broken linkify fixes Redocly#1655 * fix: fix accidentally removed onLoaded fixes Redocly#1656 * chore: fix sync workflow * chore: v2.0.0-rc.55 * chore: fix demo slack url * chore: changed docs sync flow * chore: added security section into pull request template * docs: improve the redoc cli README (Redocly#1679) - Break some long lines - Add some articles (the, a) - Add a couple links for additional context - Expand the SSR acronym - Describe what --watch does * feat: added localization for some labels (Redocly#1675) * feat: add yaml highlight (Redocly#1684) * feat: add yaml highlight * chore: upgrade prism version * chore(cli): v0.12.2 * chore: bumps npm-shrinkwrap (Redocly#1688) * chore: upgrade shrinkwrap * chore: fix dockerfile * fix: handle empty object in security array (Redocly#1678) * docs: add real-life usage example: BoxKnight (Redocly#1651) * chore: add github template (Redocly#1708) * chore: add headers to github templates (Redocly#1710) * fix: improve openapi 3.1 (Redocly#1700) * fix: hideLoading options in redoc standalone (Redocly#1709) * feat: add github action to build docker images and push to ghcr.io on release (Redocly#1614) * fix: nullable object's fields were missing (Redocly#1721) * chore: up version for release (Redocly#1722) * chore: add change log for v2.0.0-rc.56(Redocly#1723) * chore(cli): v0.12.3 * docs(GSOD): Adds new quickstart doc (Redocly#1718) * docs: fix broken links in intro (Redocly#1730) * Removes content that is now in documentation and adds link to docs * fix: Schema for events incorrectly omits readOnly and includes writeOnly (Redocly#1720 Redocly#1540) * Apply suggestions from code review * Update README.md Co-authored-by: Adam Altman <adam@rebilly.com> * Updates readme with about section and organizes features list * Adds some notes to deployment * feat: new option generatedPayloadSamplesMaxDepth (Redocly#1642) * chore: update libs (Redocly#1707) * fix: Redoc spelling * Updates per reviews and adds new logo * Minor edits * fix: scrolling to the first item (Redocly#1753) * Adds comparison table and OpenAPI link section * Minor edit * Updates image src * fix: OpenAPI 3.1: Missing description when $ref used Redocly#1727 * fix: OpenAPI 3.1: Missing description when $ref used Redocly#1727 * fix: improve publish action scripts (Redocly#1729) * feat: add q/kdb+ syntax highlighting (Redocly#1605) * fix: The number of items in the array in the array is incorrect Redocly#1762 (Redocly#1763) * fix: fix deref logic for oas3.1 (Redocly#1767) * chore: remove commented out code (Redocly#1768) * fix: No match scenario in search (Redocly#1667) Co-authored-by: Alex Varchuk <olexandr.varchuk@gmail.com> * chore: v2.0.0-rc.57 (Redocly#1770) * chore: update publish cli workflow * chore: fix publish workflow and disable s3 demo * chore: fix publish workflow again * chore(cli): v0.13.0 (Redocly#1771) * chore: fix cli publish workflow * fix: Default boolean property value not rendered Redocly#1779 (Redocly#1781) * chore: remove broken badges from README * [GSoD]Reorganizes the quickstart into a deployment guide and quickstart (Redocly#1749) * Reorganizes the quickstart into a deployment guide and quickstart * Minor edits * fix: minor formatting issue * fix: simplify phrasing * Adds redirects, link to preview-docs docs, and other review edits * remove IE polyfills as IE is no longer supported Co-authored-by: Ivana Isadora Devcic <33730345+skadinna@users.noreply.github.com> * sync: Synced local 'docs/' with remote 'docs/redoc/' * fix: mobile view in docker image (Redocly#1795) * sync: Synced local 'docs/' with remote 'docs/redoc/' * sync: Synced local 'docs/' with remote 'docs/redoc/' * chore: run prettier & add husky pre-commit hook (Redocly#1800) * fix: exclusiveMin/Max shows incorect range (Redocly#1799) * fix: exclusiveMin/Max shows incorect range * cover all number range cases & add unit tests * add more tests * fix maximum value * simplify humanizeNumberRange function * simplify exclusive checks * Update src/utils/openapi.ts Co-authored-by: Roman Hotsiy <gotsijroman@gmail.com> * update test coverage * linting * revert weird prettier changes * add md files to prettier ignore Co-authored-by: Roman Hotsiy <gotsijroman@gmail.com> * fix: add browser build for webpack 5 (Redocly#1796) * chore: v2.0.0-rc.58 (Redocly#1808) * chore(cli): v0.13.1 (Redocly#1809) * fix this Co-authored-by: Anna Stasiuk <stasiukanya@gmail.com> Co-authored-by: romanhotsiy <gotsijroman@gmail.com> Co-authored-by: jabba-jedi <menggan@yandex.ru> Co-authored-by: Karl Scheirer <kscheirer@users.noreply.github.com> Co-authored-by: baijunyao <baijunyao@baijunyao.com> Co-authored-by: Anton Kozachuk <54616703+AntonKozachuk@users.noreply.github.com> Co-authored-by: Oleksiy Kachynskyy <okachynskyy@users.noreply.github.com> Co-authored-by: 迷渡 <justjavac@gmail.com> Co-authored-by: Patrick Demers <patrickdemers6@gmail.com> Co-authored-by: Kurt Furbush <kurtfurbush@gmail.com> Co-authored-by: Andriy Leliv <andrii.leliv@gmail.com> Co-authored-by: Olivier Beaulieu <olivierbeaulieu@users.noreply.github.com> Co-authored-by: langhabel <langhabel@users.noreply.github.com> Co-authored-by: Yevhenii Hyzyla <hyzyla@gmail.com> Co-authored-by: AlexVarchuk <olexandr.varchuk@gmail.com> Co-authored-by: Ivan Shvets <shvets.email1@gmail.com> Co-authored-by: Ivan Shvets <37488015+Leocete@users.noreply.github.com> Co-authored-by: Roman <marshevskyy@gmail.com> Co-authored-by: Waldir Pimenta <waldyrious@gmail.com> Co-authored-by: ILya Volchenkov <zvolkzrus@gmail.com> Co-authored-by: Andrea Mugx <andrea.mugnaini@fundingcircle.com> Co-authored-by: Valdir Mendes <valdir.mfjesus@hotmail.com> Co-authored-by: Marius Butuc <marius.butuc@gmail.com> Co-authored-by: Roelof Kallenkoot <roelof000@gmail.com> Co-authored-by: Heather Cloward <heathercloward@gmail.com> Co-authored-by: Adam Altman <adam@redoc.ly> Co-authored-by: Andriy Zaleskyy <zal3sky@gmail.com> Co-authored-by: Ivana Isadora Devcic <33730345+skadinna@users.noreply.github.com> Co-authored-by: Swapnil Ogale <swapnilogale@gmail.com> Co-authored-by: Adam Altman <adam@rebilly.com> Co-authored-by: Mark Theisen <mark.theisen@spothero.com> Co-authored-by: Roman Marshevskyy <roman.marshevskyy@redoc.ly> Co-authored-by: kylenarocroc <3884351+kylenarocroc@users.noreply.github.com> Co-authored-by: Gabriel Simon Gianotti <gabrielgianotti5@gmail.com> Co-authored-by: raghavi92 <raghavi92@gmail.com> Co-authored-by: redocly-bot <null> Co-authored-by: Oprysk Vyacheslav <oprusk230992@gmail.com>
What/Why/How?
As part of GSOD, I am working on updating Redoc's documentation. One thing I noticed is the quickstart guide currently does not live on the documentation site, but only in the readme file. I have taken the quickstart guide and broken it into files and folders and included a sidebars.yaml file with how it would be arranged in the left-nav. I also added some extra tips and information for initializing npm on a project with a package.json file and simulating a local server with python or node.js. The screenshots include a React component doc that I will add in a future PR.
Reference
I have created a card for this task on my fork project's Kanban board: https://github.com/HCloward/redoc/projects/1#card-66462515
Testing
I do include a few links which should probably be tested. Also, I am open to the topic naming - let me know what y'all think.
Screenshots (optional)
Check yourself