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

Integration of new WIP Bevy Book #624

Closed

Conversation

Captain-Of-Coit
Copy link

This PR is the result of the discussion in #623

In short, it implements the following:

  • Hide book from public for now, only accessible by URL
  • Versioned by Bevy version
  • Basic scaffolded structure
  • Disallow indexing robots for new Bevy book for now
  • Add Book contribution guidelines outlining workflow described in this issue's discussion
  • Redirects all /learn/book/* paths to /learn/quick-start/* as "old" book was moved there, so we're not breaking any links out in the wild

It was made in 7 separate commits for each one of the above (+ 1 to fix markdownlint issues), and is best reviewed commit by commit as to not be overwhelmed:

Minimal changes to add hidden book (b20d68e)

This change introduces the minimal amount of changes to accomplish the
following:

  • Old "book" is now Quick Start
  • New book has a initial version (v0.11.0) with one page
  • A link which defaults to being hidden has been added to the list of
    links on /learn

Pull in book structure from new-book (6bd3b5d)

  • This incorporates changes from 97fef72, which is latest commit on new-book branch
  • Smallest amount of changes to get the overall book structure change
  • Various styling / minor fixes most probably missing from new-book
    • These can be applied later, right now a lot of conflicts so defer
  • Redirects properly setup to go the first section

Co-authored-by: Alice Cecile alice.i.cecile@gmail.com

Disallow indexing of new book (b2b1178)

This is a temporary measure in order to stop Google et al from indexing
the book before a first version been finalized. Pages within the book
won't show up in any search results and can only be accessed by direct
URL access for now.

First draft of Contribution Guidelines for Bevy Book (b81dc3c)

Taken from summarizing #623

First version of a version picker for Bevy Book (af2dac4)

Added to the bottom of the Book section list on the left.

  • Reads versions from content/learn/book/versions.toml so we can start
    working on the book for a new version and have the content in main
    without neccessarly publishing it on the website

Address markdownlint issues (036aa49)

Redirect everything from /learn/book/* to /learn/quick-start/* (a9e39ea)

Pages that been checked to redirect correctly:

https://bevyengine.org/learn/book/introduction/
https://bevyengine.org/learn/book/getting-started/
https://bevyengine.org/learn/book/getting-started/setup/
https://bevyengine.org/learn/book/getting-started/apps/
https://bevyengine.org/learn/book/getting-started/ecs/
https://bevyengine.org/learn/book/getting-started/plugins/
https://bevyengine.org/learn/book/getting-started/resources/
https://bevyengine.org/learn/book/next-steps/
https://bevyengine.org/learn/book/contributing/
https://bevyengine.org/learn/book/contributing/code/
https://bevyengine.org/learn/book/contributing/docs/
https://bevyengine.org/learn/book/troubleshooting/

Everything should redirect properly from:

https://bevyengine.org/learn/book/*

To:

https://bevyengine.org/learn/quick-start/*


@alice-i-cecile @cart as mentioned in the issue, the idea here is to get something basic in place that can go into main asap so we can begin to iterate on the book contents and everything else from a common base, instead of long-lived branches and PRs.

Captain-Of-Coit and others added 7 commits April 18, 2023 22:57
This change introduces the minimal amount of changes to accomplish the
following:

- Old "book" is now Quick Start
- New book has a initial version (v0.11.0) with one page
- A link which defaults to being hidden has been added to the list of
  links on /learn
- This incorporates changes from 97fef72, which is latest commit on new-book branch
- Smallest amount of changes to get the overall book structure change
- Various styling / minor fixes most probably missing from new-book
  - These can be applied later, right now a lot of conflicts so defer
- Redirects properly setup to go the first section

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
This is a temporary measure in order to stop Google et al from indexing
the book before a first version been finalized. Pages within the book
won't show up in any search results and can only be accessed by direct
URL access for now.
Added to the bottom of the Book section list on the left.

- Reads versions from `content/learn/book/versions.toml` so we can start
  working on the book for a new version and have the content in `main`
  without neccessarly publishing it on the website
@alice-i-cecile
Copy link
Member

alice-i-cecile commented Apr 20, 2023

For other reviewers: you can check the content of the new book at http://127.0.0.1:1111/learn/book/v0.11.0/welcome/ once your local copy of zola is serving this PR.

@alice-i-cecile
Copy link
Member

Site builds successfully for me, and the existing book works. New book also appears to be functional.

Concerns:

  1. It feels strange to me that we're not making use of the draft property in the front matter of zola at all. Perhaps this should be used for fully incomplete pages?
  2. The extra layer of nesting in the book sidebar for Bevy Book 0.11.0 is unhelpful: I don't think this is worth the real estate.

image

  1. Not super keen on the version selection living in the side bar (I much prefer it on top like on docs.rs), but I wouldn't block this PR on improving that.

@Captain-Of-Coit
Copy link
Author

@alice-i-cecile

  1. Yeah, I saw it but decided against using it as links.toml and versions.toml basically sets the entire version of the book as draft, as it'll be hidden from the public (but still built, so we can verify it works as it should). So links.toml decides which version is the latest published one, versions.toml decides which versions should be visible in the version selector
  2. Agree, will adjust
  3. Yeah, could be done nicer for sure, but in order to reduce the amount of work that goes into this small stepping stone, I think it's best we opt for incremental improvements after it's been merged to main.

Closing this PR until versioning discussion over at #623 been resolved, and future PRs will be split up commit-by-commit instead

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

Successfully merging this pull request may close these issues.

None yet

2 participants