[Merged by Bors] - Add automatic docs deployment to GitHub Pages #3535

james7132 · 2022-01-03T00:38:30Z

Objective

Partially address #407 by setting up automated deployments of bevy's API reference to GitHub Pages.

Solution

Set up a GitHub Actions workflow that builds the docs on every push to main and pushes a new commit to a gh-pages (or docs branch).

A few smaller additions to better address #407:

A top level redirect was added to take "docs.bevyengine.org" directly to the bevy crate docs.
A GitHub Pages CNAME file for supporting a publicly viewable domain instead of github.io
A robots.txt file is added to disable all search engine crawlers that respect it from crawling it (avoid having conflicting Google search results)
A .nojekyl file to speed up deployments since there is no Jekyll templating in the output.

This may require configuration of the GITHUB_TOKEN of the CI to successfully run this.

Followup

For this to completely resolve #407, a subdomain of https://bevyengine.org/ needs to be set up to point to the CNAME location. This is initially set to "dev-docs.bevyengine.org".

alice-i-cecile

This will be very useful. The workflow looks reasonable to me, and it's very clear.

Nilirad · 2022-01-03T07:58:52Z

Great! This will close bevyengine/bevy-website#181.

mockersf

I think it needs to be made very clear in the docs deployed that this would be the doc for Bevy main and not the released version.
Maybe a custom logo with "main" added? Or a sticky header bar that would say "Bevy main - version under development"?

Nilirad · 2022-01-03T08:29:29Z

A message on top could say "Development build docs. Click for the latest release docs", or something like that.

Alternatively, we can have a dropdown menu like docs.rs to choose between development and release docs.

james7132 · 2022-01-03T19:58:31Z

Added a sed command that changes the icon out for something more noticeable., and added a header.html shim to force Google not to index, even when linked from other sites. Other search engines should basically stop at the robots.txt.

NiklasEi · 2022-01-03T20:52:03Z

Before more people go looking: the new icon is coming in bevyengine/bevy-website#234

This adds a PNG icon for denoting the development docs made from bevy's `main` branch. Added as suggested in bevyengine/bevy#3535. If it doesn't show up in the diff, this is how it looks right now: ![image](https://user-images.githubusercontent.com/3137680/147969010-2092c921-fb53-4549-981b-8a7467cf3de0.png) Co-authored-by: Aevyrie Roessler <aevyrie@gmail.com>

james7132 · 2022-03-15T08:27:41Z

With bevyengine/bevy-website#234 merged, @mockersf, any other thing that's needed? It's a little hard to notice right now, but it should be enough to distinguish between it and docs.rs. I could add a sticky banner as suggested earlier, but --html-before-content seems to shove it in a row-oriented flexbox due to the navbar. Not familiar enough with HTML/CSS to make it actually stick above everything.

.github/workflows/docs.yml

mockersf · 2022-03-15T08:42:24Z

This should be good to go now.

The target domain/url is something that is up to Cart. Maybe it should not live on the website / under a bevyengine.org url as we try to keep the website only for the released version? Maybe a subdomain would be enough to differentiate?

I think the url where it would be deployed without custom domain would be https://bevyengine.github.io/bevy, that could help with having website for release, GitHub for in development?

Co-authored-by: François <mockersf@gmail.com>

cart · 2022-03-15T20:27:14Z

Yeah I'm ready to move forward on this. I do think that docs.bevyengine.org is the wrong name for "in development / unstable" docs. I do think a github url is a reasonable way to correlate the context to "in development", but its worth calling out that github also hosts our "stable releases and branches". We might be able to make it even more clear with a custom url. unstable-docs.bevyengine.org, dev-docs.bevyengine.org, dev-api.bevyengine.org etc.

I think I like the dev-docs prefix, for symmetry with docs.rs. I am interested to hear what everyone else thinks.

james7132 · 2022-03-15T20:34:08Z

I agree with the dev-docs subdomain. It seems recognizable at first glance, shorter than unstable-docs, and doesn't look like a REST API subdomain, unlike dev-api.

cart · 2022-03-15T21:52:01Z

Cool lets roll with that. I'll get the domain set up.

cart · 2022-03-15T22:06:16Z

We might actually need to merge this pr first. Can you update the domain?

cart · 2022-03-15T22:42:18Z

bors r+

# Objective Partially address #407 by setting up automated deployments of `bevy`'s API reference to GitHub Pages. ## Solution Set up a GitHub Actions workflow that builds the docs on every push to `main` and pushes a new commit to a `gh-pages` (or `docs` branch). A few smaller additions to better address #407: - A top level redirect was added to take "docs.bevyengine.org" directly to the `bevy` crate docs. - A GitHub Pages CNAME file for supporting a publicly viewable domain instead of `github.io` - A robots.txt file is added to disable all search engine crawlers that respect it from crawling it (avoid having conflicting Google search results) - A .nojekyl file to speed up deployments since there is no Jekyll templating in the output. This may require configuration of the `GITHUB_TOKEN` of the CI to successfully run this. ## Followup For this to completely resolve #407, a subdomain of https://bevyengine.org/ needs to be set up to point to the CNAME location. This is initially set to "dev-docs.bevyengine.org". Co-authored-by: Carter Anderson <mcanders1@gmail.com>

bors · 2022-03-15T23:31:28Z

Pull request successfully merged into main.

Build succeeded:

# Objective - #3535 introduced deploying docs with an error in sed command ## Solution - fix sed command - make the command cross platform

# Objective - #3535 introduced deploying docs without installing dependencies - https://github.com/bevyengine/bevy/runs/5562769081?check_suite_focus=true ## Solution - copied https://github.com/bevyengine/bevy/blob/6ff17eaab8aad54bcb3d79055846c27ca0251fcc/.github/workflows/ci.yml#L270-L271

# Objective Partially address bevyengine#407 by setting up automated deployments of `bevy`'s API reference to GitHub Pages. ## Solution Set up a GitHub Actions workflow that builds the docs on every push to `main` and pushes a new commit to a `gh-pages` (or `docs` branch). A few smaller additions to better address bevyengine#407: - A top level redirect was added to take "docs.bevyengine.org" directly to the `bevy` crate docs. - A GitHub Pages CNAME file for supporting a publicly viewable domain instead of `github.io` - A robots.txt file is added to disable all search engine crawlers that respect it from crawling it (avoid having conflicting Google search results) - A .nojekyl file to speed up deployments since there is no Jekyll templating in the output. This may require configuration of the `GITHUB_TOKEN` of the CI to successfully run this. ## Followup For this to completely resolve bevyengine#407, a subdomain of https://bevyengine.org/ needs to be set up to point to the CNAME location. This is initially set to "dev-docs.bevyengine.org". Co-authored-by: Carter Anderson <mcanders1@gmail.com>

# Objective - bevyengine#3535 introduced deploying docs with an error in sed command ## Solution - fix sed command - make the command cross platform

# Objective - bevyengine#3535 introduced deploying docs without installing dependencies - https://github.com/bevyengine/bevy/runs/5562769081?check_suite_focus=true ## Solution - copied https://github.com/bevyengine/bevy/blob/6ff17eaab8aad54bcb3d79055846c27ca0251fcc/.github/workflows/ci.yml#L270-L271

# Objective Partially address bevyengine#407 by setting up automated deployments of `bevy`'s API reference to GitHub Pages. ## Solution Set up a GitHub Actions workflow that builds the docs on every push to `main` and pushes a new commit to a `gh-pages` (or `docs` branch). A few smaller additions to better address bevyengine#407: - A top level redirect was added to take "docs.bevyengine.org" directly to the `bevy` crate docs. - A GitHub Pages CNAME file for supporting a publicly viewable domain instead of `github.io` - A robots.txt file is added to disable all search engine crawlers that respect it from crawling it (avoid having conflicting Google search results) - A .nojekyl file to speed up deployments since there is no Jekyll templating in the output. This may require configuration of the `GITHUB_TOKEN` of the CI to successfully run this. ## Followup For this to completely resolve bevyengine#407, a subdomain of https://bevyengine.org/ needs to be set up to point to the CNAME location. This is initially set to "dev-docs.bevyengine.org". Co-authored-by: Carter Anderson <mcanders1@gmail.com>

# Objective - bevyengine#3535 introduced deploying docs with an error in sed command ## Solution - fix sed command - make the command cross platform

# Objective - bevyengine#3535 introduced deploying docs without installing dependencies - https://github.com/bevyengine/bevy/runs/5562769081?check_suite_focus=true ## Solution - copied https://github.com/bevyengine/bevy/blob/6ff17eaab8aad54bcb3d79055846c27ca0251fcc/.github/workflows/ci.yml#L270-L271

james7132 added 2 commits January 2, 2022 19:25

Add automatic docs deployment to gh-pages

381ad9e

Fix redirect

76d0025

alice-i-cecile requested a review from mockersf January 3, 2022 01:22

alice-i-cecile added A-Meta About the project itself C-Docs An addition or correction to our documentation labels Jan 3, 2022

alice-i-cecile approved these changes Jan 3, 2022

View reviewed changes

mockersf requested changes Jan 3, 2022

View reviewed changes

james7132 mentioned this pull request Jan 3, 2022

[Merged by Bors] - Add a dedicated icon for a main branch docs site bevyengine/bevy-website#234

Closed

New icon and meta noindex

165beba

mockersf mentioned this pull request Mar 14, 2022

Check for dead links in CI bevyengine/bevy-website#177

Open

Merge branch 'main' into docs-deploy-ci

7a07472

mockersf reviewed Mar 15, 2022

View reviewed changes

.github/workflows/docs.yml Outdated Show resolved Hide resolved

mockersf approved these changes Mar 15, 2022

View reviewed changes

Update .github/workflows/docs.yml

3acae8d

Co-authored-by: François <mockersf@gmail.com>

update subdomain

8f1a9dd

bors bot changed the title ~~Add automatic docs deployment to GitHub Pages~~ [Merged by Bors] - Add automatic docs deployment to GitHub Pages Mar 15, 2022

bors bot closed this Mar 15, 2022

mockersf mentioned this pull request Mar 15, 2022

[Merged by Bors] - Deploy dev docs - fix sed command #4221

Closed

bors bot pushed a commit that referenced this pull request Mar 15, 2022

Deploy dev docs - fix sed command (#4221)

6ff17ea

# Objective - #3535 introduced deploying docs with an error in sed command ## Solution - fix sed command - make the command cross platform

mockersf mentioned this pull request Mar 16, 2022

[Merged by Bors] - Deploy dev docs - install dependencies #4222

Closed

james7132 mentioned this pull request Mar 21, 2022

Online docs for main #1731

Closed

james7132 deleted the docs-deploy-ci branch March 21, 2022 01:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Merged by Bors] - Add automatic docs deployment to GitHub Pages #3535

[Merged by Bors] - Add automatic docs deployment to GitHub Pages #3535

james7132 commented Jan 3, 2022 •

edited

Loading

alice-i-cecile left a comment

Nilirad commented Jan 3, 2022

mockersf left a comment

Nilirad commented Jan 3, 2022

james7132 commented Jan 3, 2022

NiklasEi commented Jan 3, 2022

james7132 commented Mar 15, 2022

mockersf commented Mar 15, 2022 •

edited

Loading

cart commented Mar 15, 2022

james7132 commented Mar 15, 2022

cart commented Mar 15, 2022

cart commented Mar 15, 2022

cart commented Mar 15, 2022

bors bot commented Mar 15, 2022

[Merged by Bors] - Add automatic docs deployment to GitHub Pages #3535

[Merged by Bors] - Add automatic docs deployment to GitHub Pages #3535

Conversation

james7132 commented Jan 3, 2022 • edited Loading

Objective

Solution

Followup

alice-i-cecile left a comment

Choose a reason for hiding this comment

Nilirad commented Jan 3, 2022

mockersf left a comment

Choose a reason for hiding this comment

Nilirad commented Jan 3, 2022

james7132 commented Jan 3, 2022

NiklasEi commented Jan 3, 2022

james7132 commented Mar 15, 2022

mockersf commented Mar 15, 2022 • edited Loading

cart commented Mar 15, 2022

james7132 commented Mar 15, 2022

cart commented Mar 15, 2022

cart commented Mar 15, 2022

cart commented Mar 15, 2022

bors bot commented Mar 15, 2022

james7132 commented Jan 3, 2022 •

edited

Loading

mockersf commented Mar 15, 2022 •

edited

Loading