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

Move manual to mdbook (take 2) #13316

Closed
wants to merge 0 commits into from
Closed

Move manual to mdbook (take 2) #13316

wants to merge 0 commits into from

Conversation

joshrotenberg
Copy link

@joshrotenberg joshrotenberg commented Sep 30, 2022

This PR converts the current single page asciidoc manual into an mdbook project in docs/manual.

Todo list:

  • create a new mdbook project in docs/manual
  • convert static manual adoc to md
  • convert features generated adoc to md
  • convert diagnostics generated adoc to md
  • convert config generated adoc to md
  • convert assists generated adoc to md
  • update xtask/src/release.rs files to point to the .md files
  • split converted manual into separate chapters
  • move docs/dev to new manual (optional, do it later?)
  • update project README.md to include links to the new mdbook site
  • add docs on mdbook and how to update the manual
  • deploy the book (need help here I think)
  • grammar/spelling/typo check
  • markdown lint

Fixes #9504.

(This is a 'take 2' on #10791. I found a much cleaner and consistent way to convert a lot of the adoc with pandoc and it was easier to start fresh with the latest master).

@bors
Copy link
Collaborator

bors commented Oct 1, 2022

☔ The latest upstream changes (presumably #13327) made this pull request unmergeable. Please resolve the merge conflicts.

@joshrotenberg
Copy link
Author

Some considerations for the navigation related to automatically generated content ...

Right now, because the four automatically generated sections (Configuration, Assists, Features and Diagnostics) produce a single markdown file for their respective items, their contents are only displayed on the main page using the mdbook toc preprocessor. Note specifically that the navigation does not have the ability to expand down and show the contents) For example:

Screen Shot 2022-10-01 at 12 53 10 PM

While my instinct would be to make them separate, in this case it seems like not cluttering the navigation with excessively long sub item lists is preferable, and just having them exist on a single page makes it easier to CtrlF through (as I believe is pointed out as a desirable feature in #9504).

Adding to the searchability, the mdbook built-in search gives good results when searching for, say, a specific assist:

Screen Shot 2022-10-01 at 1 04 00 PM

More screenshots with other themes ...

Installation
Screen Shot 2022-10-01 at 12 47 57 PM

Contributing guide (previously the content in docs/dev)

Screen Shot 2022-10-01 at 1 05 02 PM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Manual needs to be more helpful, friendly, and better organized
2 participants