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

Publish API Documentation for Master Branch #407

Closed
zicklag opened this issue Aug 31, 2020 · 4 comments
Closed

Publish API Documentation for Master Branch #407

zicklag opened this issue Aug 31, 2020 · 4 comments
Labels
A-Build-System Related to build systems or continuous integration C-Docs An addition or correction to our documentation C-Feature A new feature, making something new possible

Comments

@zicklag
Copy link
Member

zicklag commented Aug 31, 2020

I was just thinking that it would be useful to have the API documentation for the master branch published to GitHub pages somewhere.

I was going to explain to @lee-orr, a beginner Rustacean, what changes were going to need to happen for #397, but I noticed that some of the API that I was going to point to had not been released yet, which meant that I can't point to the documentation for it. I didn't end up needing it in that case, but it seems like it could be useful.

@CleanCut
Copy link
Member

CleanCut commented Sep 1, 2020

I suggest avoiding adding to the overhead of the project at this early stage. There's a lot of things like this that are nice, but quickly add up to a lot of infrastructure complexity and maintenance. Rather than serving up API docs for master, I think it would be more healthy to:

  • Release very frequently, so there isn't much desire for referencing the master docs
  • Show folks how to generate their own master docs locally (It could just be a sentence at the top of the API docs front page, for example)

@karroffel karroffel added A-Build-System Related to build systems or continuous integration C-Docs An addition or correction to our documentation C-Feature A new feature, making something new possible labels Sep 1, 2020
@zicklag
Copy link
Member Author

zicklag commented Sep 1, 2020

I'll buy that. 🙂 👍

@memoryruins
Copy link
Contributor

memoryruins commented Nov 12, 2020

That would be useful (now or eventually). I imagine something like cargo doc --no-deps -p bevy so that it doesn't include docs for all dependencies too (which is what I use locally). It would also help the users of git versions to help audit the docs in-between releases.

@Moxinilian
Copy link
Member

Moxinilian commented Nov 12, 2020

If the master docs are ever provided on the website, it is of utmost importance search engines do not reference it. Amethyst had a ton of issues with people being misdirected into the wrong documentation.

@bors bors bot closed this as completed in e020c57 Mar 15, 2022
aevyrie pushed a commit to aevyrie/bevy that referenced this issue Jun 7, 2022
# 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 <[email protected]>
ItsDoot pushed a commit to ItsDoot/bevy that referenced this issue Feb 1, 2023
# 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 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-Build-System Related to build systems or continuous integration C-Docs An addition or correction to our documentation C-Feature A new feature, making something new possible
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants