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

Reorganize website docs #1806

Merged
merged 11 commits into from
Mar 18, 2021
Merged

Reorganize website docs #1806

merged 11 commits into from
Mar 18, 2021

Conversation

mwachs5
Copy link
Contributor

@mwachs5 mwachs5 commented Mar 10, 2021

After realizing that the oh-so-handy Cookbook wasn't discoverable on the website, I went on a bender of finally getting rid of the "Wiki (Deprecated)" section, which turned into a bunch of docs cleanup.

This PR:

  • Creates a Developers and Resources section, then moves everything out of the wiki (Deprecated) into one of the existing sections, the vast majority into the explanations category. I thought most of the content was of that sort. I did not try to split up any individual articles.
  • applies mdoc checks as much as possible around all the code snippets and corrected a few things found in this way
  • moved all the .md "landing" pages for each section from the website repo directly to here for a more consistent editing experience, and put links on each of them to the content
  • Broke up the "Introduction" section into "Introduction" and "Motivation".
  • Added the information about loading memories into the Experimental Features section
  • I somewhat cleaned up the FAQ section, but as it is I don't think the "how to verilog" instructions are solid enough so my website PR does not include the FAQ Cleaned up the FAQ section and added it to the Resources

Contributor Checklist

  • Did you add Scaladoc to every public function/method?
  • Did you add at least one test demonstrating the PR?
  • Did you delete any extraneous printlns/debugging code? -- Not yet one thing is commented out i need to debug.
  • Did you specify the type of improvement?
  • Did you add appropriate documentation in docs/src?
  • Did you state the API impact?
  • Did you specify the code generation impact?
  • Did you request a desired merge strategy?
  • Did you add text to be included in the Release Notes for this change?

Type of Improvement

  • documentation

API Impact

Backend Code Generation Impact

No impact on backend code

Desired Merge Strategy

  • Squash: The PR will be squashed and merged (choose this if you have no preference.

Release Notes

Documentation reorganized, wiki content redistributed.

Reviewer Checklist (only modified by reviewer)

  • Did you add the appropriate labels?
  • Did you mark the proper milestone (3.2.x, 3.3.x, 3.4.0, 3.5.0) ?
  • Did you review?
  • Did you check whether all relevant Contributor checkboxes have been checked?
  • Did you mark as Please Merge?

Copy link
Contributor

@jackkoenig jackkoenig left a comment

Choose a reason for hiding this comment

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

Overall this looks good, I do have a couple of questions / comments

docs/src/explanations/interval-type.md Outdated Show resolved Hide resolved
docs/src/explanations/introduction.md Outdated Show resolved Hide resolved
@jackkoenig
Copy link
Contributor

I'd also like to note my comment here: #1805 (comment) There's at least 1 page still existing on the Wiki that doesn't exist on the website.

@mwachs5
Copy link
Contributor Author

mwachs5 commented Mar 11, 2021

"I'd also like to note my comment here: #1805 (comment) There's at least 1 page still existing on the Wiki that doesn't exist on the website." -- added this content under the experimental features section

docs/src/developers/style.md Outdated Show resolved Hide resolved
@mwachs5 mwachs5 changed the title Reorganize website docs [WIP] Reorganize website docs Mar 16, 2021
@mwachs5
Copy link
Contributor Author

mwachs5 commented Mar 16, 2021

@jackkoenig , @seldridge I think I am ready for a review on this. There is one unresolved change moving from chisel3.Driver to ChiselStage. This is also seemingly failing CI due to inability to grab dependencies.

Copy link
Contributor Author

@mwachs5 mwachs5 left a comment

Choose a reason for hiding this comment

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

Found the remaining question I had about getting the annotations example to work (@azidar , @jackkoenig ?)

docs/src/explanations/annotations.md Show resolved Hide resolved
@mwachs5 mwachs5 changed the title [WIP] Reorganize website docs Reorganize website docs Mar 16, 2021
Copy link
Contributor

@jackkoenig jackkoenig left a comment

Choose a reason for hiding this comment

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

This is fantastic, thank you so much @mwachs5! I have a few suggestions but this is a huge improvement!

@jackkoenig jackkoenig added this to the 3.4.x milestone Mar 16, 2021
Copy link
Member

@seldridge seldridge left a comment

Choose a reason for hiding this comment

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

Amazing.

Thanks for tackling this @mwachs5!

build.sbt Outdated Show resolved Hide resolved
docs/src/cookbooks/cookbook.md Outdated Show resolved Hide resolved
docs/src/introduction.md Show resolved Hide resolved
build.sbt Outdated Show resolved Hide resolved
docs/src/explanations/explanations.md Outdated Show resolved Hide resolved
docs/src/cookbooks/cookbooks.md Outdated Show resolved Hide resolved
docs/src/cookbooks/cookbook.md Outdated Show resolved Hide resolved
docs/src/cookbooks/cookbook.md Outdated Show resolved Hide resolved
* guard code examples with mdoc and fix errors encountered along the way

* move some website content here vs splitting the content across two repos

* Bring in the interval-types and loading memories content so that it will be visible from the website

* remove all references to the wiki (deprecated)

* Remove reference to Wiki from the README
@jackkoenig
Copy link
Contributor

I've realized why the links don't work if we put .md at the end of them but they did once before. Previously, all of this mdoc was in the website repo and sbt-microsites specifically supports pointing to your mdoc. I'm assuming they do the whole "link to md converted to link to html" conversion for you. Not yet sure how to solve, but I think that's the cause.

docs/src/resources/faqs.md Outdated Show resolved Hide resolved
docs/src/resources/faqs.md Outdated Show resolved Hide resolved
Co-authored-by: Jack Koenig <koenig@sifive.com>
@jackkoenig jackkoenig merged commit f1ad5b5 into master Mar 18, 2021
mergify bot pushed a commit that referenced this pull request Mar 18, 2021
Updates to chisel3 documentation for website:
* guard code examples with mdoc and fix errors encountered along the way
* move some website content here vs splitting the content across two repos
* Bring in the interval-types and loading memories content so that it will be visible from the website
* remove all references to the wiki (deprecated)
* Remove reference to Wiki from the README
* fix tabbing and compile of chisel3-vs-chisel2 section
* Appendix: faqs now guarded and compile
* FAQs: move to resources section

(cherry picked from commit f1ad5b5)
@mergify mergify bot added the Backported This PR has been backported label Mar 18, 2021
mergify bot added a commit that referenced this pull request Mar 19, 2021
Updates to chisel3 documentation for website:
* guard code examples with mdoc and fix errors encountered along the way
* move some website content here vs splitting the content across two repos
* Bring in the interval-types and loading memories content so that it will be visible from the website
* remove all references to the wiki (deprecated)
* Remove reference to Wiki from the README
* fix tabbing and compile of chisel3-vs-chisel2 section
* Appendix: faqs now guarded and compile
* FAQs: move to resources section

(cherry picked from commit f1ad5b5)

Co-authored-by: Megan Wachs <megan@sifive.com>
@jackkoenig jackkoenig deleted the reorganize-website-docs branch March 19, 2021 01:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Backported This PR has been backported
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants