Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(docs): Add some "how-to" documentation for website development #23311

Merged
merged 8 commits into from
Dec 12, 2024

Conversation

Josmithr
Copy link
Contributor

@Josmithr Josmithr commented Dec 12, 2024

Includes notes on:

  • "Documents" vs "Pages"
  • Modifying sidebars
  • Docs versioning

AB#24262

@Josmithr
Copy link
Contributor Author

For reviewers:

  • I'm looking for feedback on what I have added so far. I've erred on the side of being somewhat minimal, and linking to Docusaurus's documentation, rather than re-stating what they have already documented. This also helps future-proof us somewhat as they update their own docs. That said, I'd still like for our own docs to be more useful than "go read Docusaurus's docs". It's a fine line to walk. Any feedback is appreciated s🙂
  • I'm also looking for suggestions for other guides that would be helpful to add. We can always add more later as needed, but I'm also happy to add more now.

@Josmithr Josmithr requested review from RishhiB, zhenmichael and a team December 12, 2024 00:30
docs/README.md Outdated

These steps are based on Docusaurus's tutorial [here](https://docusaurus.io/docs/versioning#tutorials).

Note: in order for API documentation to be available for the new version, you will need to ensure that API model artifacts are being published for the new major version series.
Copy link
Contributor Author

@Josmithr Josmithr Dec 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@zhenmichael I'd like to document the steps for setting up API model artifacts publishing for a new release branch, if possible. Hoping you can help me fill that in, assuming we have a process in place for that 🙂

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good overall! The pubishing pipeline should automatically generate new artifacts in the blob storage the first time a new major version release version is run. As long as the config file is updated the download-apis step should have access the correct artifacts.

Copy link
Contributor

@WayneFerrao WayneFerrao left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reads well and I like the references to the Docusaurus docs!

Copy link
Contributor

@alexvy86 alexvy86 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pretty clear IMO 👍

@Josmithr Josmithr marked this pull request as ready for review December 12, 2024 21:17
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot reviewed 1 out of 2 changed files in this pull request and generated 1 suggestion.

Files not reviewed (1)
  • .vscode/settings.json: Language not supported

Tip: Copilot only keeps its highest confidence comments to reduce noise and keep you focused. Learn more

docs/README.md Outdated Show resolved Hide resolved
docs/README.md Outdated

These steps are based on Docusaurus's tutorial [here](https://docusaurus.io/docs/versioning#tutorials).

Note: in order for API documentation to be available for the new version, you will need to ensure that API model artifacts are being published for the new major version series.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good overall! The pubishing pipeline should automatically generate new artifacts in the blob storage the first time a new major version release version is run. As long as the config file is updated the download-apis step should have access the correct artifacts.

@Josmithr Josmithr enabled auto-merge (squash) December 12, 2024 23:47
@Josmithr Josmithr merged commit 459bbd5 into microsoft:main Dec 12, 2024
27 checks passed
Copy link
Contributor

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  170006 links
    1595 destination URLs
    1825 URLs ignored
       0 warnings
       0 errors


@Josmithr Josmithr deleted the docs/how-tos branch December 13, 2024 00:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: website base: main PRs targeted against main branch
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants