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

Update deploying-your-docs.md re: GitHub Pages #3692

Open
wants to merge 5 commits into
base: master
Choose a base branch
from

Conversation

HumbleDeer
Copy link

re: GitHub Pages

  • GitHub changed the default branch for new repositories to "main" instead of "master"
  • Reworded some rections to clarify the intent and/or process
  • Changed a note into a NOTE: section
  • Unified word usage between the Project and User/Organisation sections. This also changes/fixes the title for Organisations/Users, as the order of these to words was reversed from the text below.

re: GitHub Pages
- GitHub changed the default branch for new repositories to "main" instead of "master"
- Reworded some rections to clarify the intent and/or process
- Changed a note into a NOTE: section
- Unified word usage between the Project and User/Organisation sections.  
  This also changes/fixes the title for Organisations/Users, as the order of these to words was reversed from the text below.
Replace more references to the `master` branch with references to the `main` branch, as per recent and new standard for new repositories by GitHub.
docs/user-guide/deploying-your-docs.md Outdated Show resolved Hide resolved
docs/user-guide/deploying-your-docs.md Outdated Show resolved Hide resolved
Organisation changed to Organization, in accordance with other spellings of the word.
@HumbleDeer HumbleDeer requested a review from trel May 1, 2024 17:47
Copy link
Contributor

@pawamoy pawamoy left a comment

Choose a reason for hiding this comment

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

Thanks for the PR! A few comments.

docs/user-guide/deploying-your-docs.md Outdated Show resolved Hide resolved
docs/user-guide/deploying-your-docs.md Outdated Show resolved Hide resolved
with the [remote_branch] configuration setting, but if you forget to change
directories before running the deploy script, it will commit to the `master`
branch of your project, which you probably don't want.
Please note that you need to explicitly point to the `mkdocs.yml` configuration
Copy link
Contributor

Choose a reason for hiding this comment

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

Is "Please" really necessary here?

Copy link
Member

Choose a reason for hiding this comment

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

+1 be sharp.

Copy link
Author

Choose a reason for hiding this comment

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

+1 be sharp.

What do you mean by this?

Copy link
Member

Choose a reason for hiding this comment

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

Be concise.

Copy link
Contributor

Choose a reason for hiding this comment

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

i.e. remove "Please" 😉

You may override the default branch with the [remote_branch] setting in the
mkdocs.yml configuration file, but forgetting to change directories before
running the deploy script will commit to the `main` branch of `my-project`,
likely overwriting the contents of your precious project.
Copy link
Contributor

Choose a reason for hiding this comment

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

Did you mean previous, or really precious? Sounds a bit too familiar. Maybe just remove it.

Copy link
Author

Choose a reason for hiding this comment

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

I did mean precious.

Copy link
Contributor

@pawamoy pawamoy May 4, 2024

Choose a reason for hiding this comment

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

OK thanks. I'd prefer we remove "precious" then. It particularly sounds bad for French readers, as we often use "precieux" sarcastically (I suspect it might be the same for other languages, and English in particular). Even if not, let's be concise as mentioned previously.

to GitHub. Therefore, you may want to verify any changes you make to the docs
beforehand by using the `build` or `serve` commands and reviewing the built
files locally.
Please note that you will not be able to review the built site before it is
Copy link
Contributor

Choose a reason for hiding this comment

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

Same remark here about "please" (I don't think it's necessary).

docs/user-guide/deploying-your-docs.md Outdated Show resolved Hide resolved
docs/user-guide/deploying-your-docs.md Outdated Show resolved Hide resolved
with the GitHub account name. Therefore, you need working copies of two
repositories on our local system. For example, consider the following file
structure:
User and Organization GitHub Pages sites are not tied to a specific project,
Copy link
Author

Choose a reason for hiding this comment

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

Suggested change
User and Organization GitHub Pages sites are not tied to a specific project,
User and Organization GitHub Pages sites are not tied to a project repository.

Copy link
Contributor

@pawamoy pawamoy May 4, 2024

Choose a reason for hiding this comment

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

Looks like this suggestion wasn't committed but is now outdated. Could you update it? It's required for the suggestion right below it to make sense.

repositories on our local system. For example, consider the following file
structure:
User and Organization GitHub Pages sites are not tied to a specific project,
and the site files are deployed to the `main` branch in a dedicated
Copy link
Author

Choose a reason for hiding this comment

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

Suggested change
and the site files are deployed to the `main` branch in a dedicated
By default, the site files are deployed to the `main` branch in a dedicated

structure:
User and Organization GitHub Pages sites are not tied to a specific project,
and the site files are deployed to the `main` branch in a dedicated
repository named with the GitHub account name. Therefore, you will need working
Copy link
Author

Choose a reason for hiding this comment

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

Suggested change
repository named with the GitHub account name. Therefore, you will need working
repository named after the GitHub account or organisation. Therefore, you will need working

User and Organization GitHub Pages sites are not tied to a specific project,
and the site files are deployed to the `main` branch in a dedicated
repository named with the GitHub account name. Therefore, you will need working
copies of two repositories on your local system. For example, consider the
Copy link
Author

Choose a reason for hiding this comment

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

Suggested change
copies of two repositories on your local system. For example, consider the
copies of two repositories on your local system: one for the website's source markdown or text files, and one for the deployed website. For example, consider the

Copy link
Author

Choose a reason for hiding this comment

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

I clarified what the two repositories actually refers to, but in reality this entire section should be rewritten. It is at present not true or the case that one needs a separate repository for the source files. As with any repository Pages site, you can choose the deployment source in the repository settings, with options for both automation with Actions or deployment from a branch of your choosing (with or without /docs subfolder) using the built-in deployment.

A proper fix for this would be to delete the organisation section in its entirety, and describe changing the deployment source if necessary.

I may or may not implement this in this PR, depending on whether it gets merged before I get to it or not.

Copy link
Contributor

Choose a reason for hiding this comment

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

Doing it in another PR sounds good to me.

docs/user-guide/deploying-your-docs.md Outdated Show resolved Hide resolved
docs/user-guide/deploying-your-docs.md Outdated Show resolved Hide resolved
with the [remote_branch] configuration setting, but if you forget to change
directories before running the deploy script, it will commit to the `master`
branch of your project, which you probably don't want.
Please note that you need to explicitly point to the `mkdocs.yml` configuration
Copy link
Author

Choose a reason for hiding this comment

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

+1 be sharp.

What do you mean by this?

You may override the default branch with the [remote_branch] setting in the
mkdocs.yml configuration file, but forgetting to change directories before
running the deploy script will commit to the `main` branch of `my-project`,
likely overwriting the contents of your precious project.
Copy link
Author

Choose a reason for hiding this comment

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

I did mean precious.

@HumbleDeer
Copy link
Author

HumbleDeer commented May 5, 2024 via email

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.

4 participants