diff --git a/.github/components/dictionary.txt b/.github/components/dictionary.txt index c12c3e17c..621aa6261 100644 --- a/.github/components/dictionary.txt +++ b/.github/components/dictionary.txt @@ -6,6 +6,7 @@ conda config DM doxxing +dropdown formatters GitHub GitKraken diff --git a/docs/contributing.md b/docs/contributing.md index f98dd62a9..ed5bc2adc 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -19,6 +19,8 @@ To serve the documentation during local development, run `mkdocs serve` from the - [Docs organization](#docs-organization) - [Adding new documentation](#adding-new-documentation) - [Linking to other pages](#linking-to-other-pages) +- [Adding images](#adding-images) +- [Phrasing](#phrasing) ## Docs organization @@ -29,9 +31,9 @@ Documentation is written as a series of markdown files nested by topic in direct - Each top-level directory should contain an `index.md` file with an overall description of what that section contains. - The `index.md` should have an L1 header with the same title as the `navbar` section. - Markdown files in each directory represent sections shown along the left sidebar. -- Nested directories within each `navbar` section should be used to add an additional bold (gray) header on the left sidebar. - - Markdown files within each nested directory will fall under this additional bold (gray) header. -- Any visual aids used in the docs should be placed in `docs/img`. +- Nested directories within each `navbar` section should be used to add an additional bold header on the left sidebar and _may_ also have an `index.md` file. + - Markdown files within each nested directory will fall under this additional bold header. +- Any visual aids used in the docs should be placed in `docs/img` (see the [adding images section](#adding-images)). ## Adding new documentation @@ -85,3 +87,23 @@ For example: ``` This sentence should link to the [pull request documentation](STUB_LINK). ``` + + +## Adding images + +All image files should be placed in `docs/img`. +Try to size images to roughly 2X the display size; this will allow the images to look ok on high-res displays without the files being too large. + +To include an image in a docs file, use the following syntax to center the image on the page: + +``` +
+ ![alt text](relative link to image file){width="number of pixels"} +
+``` + +## Phrasing + +For consistency, please use the following: + +- Refer to `github.com` as "GitHub" (but without quotes) except when providing specific links. diff --git a/docs/img/add-upstream-remote-1.png b/docs/img/add-upstream-remote-1.png new file mode 100644 index 000000000..a0f56a580 Binary files /dev/null and b/docs/img/add-upstream-remote-1.png differ diff --git a/docs/img/add-upstream-remote-2.png b/docs/img/add-upstream-remote-2.png new file mode 100644 index 000000000..3dc67587c Binary files /dev/null and b/docs/img/add-upstream-remote-2.png differ diff --git a/docs/img/add-upstream-remote-3.png b/docs/img/add-upstream-remote-3.png new file mode 100644 index 000000000..b06a312c7 Binary files /dev/null and b/docs/img/add-upstream-remote-3.png differ diff --git a/docs/technical-setup/clone-the-repo.md b/docs/technical-setup/clone-the-repo.md new file mode 100644 index 000000000..4cbe87dd2 --- /dev/null +++ b/docs/technical-setup/clone-the-repo.md @@ -0,0 +1,59 @@ +# Clone the repository + +After [forking the `OpenScPCA` repository](./fork-the-repo.md), you will need to _clone_ your forked repository to your computer. +Cloning provides you with a local copy of the repository to work with. +You will need to clone the repository to every computer (or remote server) you want to use to contribute to the project. + +!!! note + You should clone your forked repository from `/OpenScPCA-analysis`, _not_ `AlexsLemonade/OpenScPCA-analysis`. + + +## Clone your forked repository + +Please follow the [instructions in this GitKraken video](https://help.gitkraken.com/gitkraken-client/open-clone-init/#cloning-an-existing-project) to clone your repository. + +This video presents two approaches to cloning: `Clone with URL`, and Clone based on your integrated GitHub account. +Either approach is fine to take, but please bear in mind the following: + +In the `Clone with URL` option, the video presents cloning with an `https` link, vs. an `SSH` link. +If you have already set up a [GitHub SSH connection](https://docs.github.com/en/authentication/connecting-to-github-with-ssh), you are welcome to use the `SSH` link version instead. +If you do not have SSH set up for GitHub, you will want to use with the `https` link as shown. +Note that an SSH connection is _not required_ to contribute to OpenScPCA. + +While watching this video, you can feel free to ignore all references to `LFS` ("large file storage"); this does not apply to `OpenScPCA-analysis`. + +## Add the project repository as a remote repository + +The next step is to link the upstream repository (`AlexsLemonade/OpenScPCA-analysis`) as a remote. +A _remote_ is a repository on GitHub that you are connected to. +Each remote repository is given a name to make referring to them easier. +For example, your forked repository on GitHub is called `origin` because it is where your local repository was cloned from. + +We will add another remote repository named `upstream` that refers to the original `AlexsLemonade/OpenScPCA-analysis` repository on GitHub. +This will be called `upstream` because it was the source that your fork came from. + +Adding the `AlexsLemonade` _upstream remote_ will allow you to interact with it from your computer which can help you keep your fork in sync with the `OpenScPCA` project. +But, you will still be working in your fork when writing analysis code. + +Follow these steps to add the upstream remote: + +1. From your repository in GitKraken, hover over the `1/1` text on the left-hand side `Remote` menu. +This text will then turn into a plus-sign icon. +Click that icon. + +
+ ![Click button to add the remote.](../img/add-upstream-remote-1.png){width="600"} +
+ +1. The following screen will prompt you to add a remote. +Select `AlexsLemonade/OpenScPCA-analysis` from the dropdown menu, and click the button `Add remote`. +
+ ![Add the upstream remote.](../img/add-upstream-remote-2.png){width="400"} +
+ +1. You should then see a second remote called `AlexsLemonade` on the left-hand side `Remote` panel. +The specific listed items under `AlexsLemonade` that you see will look different from the screenshot below; this is expected. +As long as you see that `AlexsLemonade` is listed in the menu, you have successfully added the upstream remote. +
+ ![View the added remote.](../img/add-upstream-remote-3.png){width="400"} +
diff --git a/docs/technical-setup/fork-the-repo.md b/docs/technical-setup/fork-the-repo.md index 294fada4c..b2ddd8ba2 100644 --- a/docs/technical-setup/fork-the-repo.md +++ b/docs/technical-setup/fork-the-repo.md @@ -4,6 +4,7 @@ You will need to create a [_fork_](https://docs.github.com/en/pull-requests/coll A fork is a copy of an _upstream_ repository (here, `AlexsLemonade/OpenScPCA-analysis` is the _upstream_) that you will own and will be in your GitHub account. As a contributor, you will perform analyses in your fork. +Just like the upstream `AlexsLemonade/OpenScPCA-analysis` repository, your fork will also be a public repository. One benefit of using a fork is that changes you make will not affect the upstream project in `AlexsLemonade/OpenScPCA-analysis`. This means you can safely work on your analyses without worrying about messing anything up in the upstream repository. @@ -19,7 +20,7 @@ Follow these steps to create your fork: 1. At the top right corner, click the "Fork" button: (The numbers you see in this screenshot may differ from the numbers on the website - that's ok!) -![Button on GitHub.com to fork a repository.](../img/fork-button.png){width="400"} +![Button on GitHub to fork a repository.](../img/fork-button.png){width="400"} 1. On the next screen, GitHub will prompt you for some settings about your fork. diff --git a/docs/technical-setup/install-a-github-client.md b/docs/technical-setup/install-a-github-client.md index ac9c3e766..8ff0c7e83 100644 --- a/docs/technical-setup/install-a-github-client.md +++ b/docs/technical-setup/install-a-github-client.md @@ -1,6 +1,6 @@ # Install a GitHub client -You will need a platform on your computer to run Git commands and interact with [GitHub.com](https://github.com). +You will need a platform on your computer to run Git commands and interact with [GitHub](https://github.com). There are many platforms you can choose, but we recommend using either [**GitKraken**](https://www.gitkraken.com/) or the [Git **command line interface**](https://git-scm.com/book/en/v2/Getting-Started-The-Command-Line). diff --git a/mkdocs.yml b/mkdocs.yml index 6084fff6b..701ea0070 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -22,8 +22,8 @@ plugins: markdown_extensions: - admonition # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#admonition - - attr_list # https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown.md#attribute-lists - + - attr_list # https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/extensions/python-markdown.md#attribute-lists + - md_in_html # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#markdown-in-html # Here is the basic structure of our navigation setup. #nav: # - Navbar section: @@ -41,6 +41,7 @@ nav: - technical-setup/index.md - technical-setup/install-a-github-client.md - technical-setup/fork-the-repo.md + - technical-setup/clone-the-repo.md - Tools for communication: # Slack, issues, discussions - communications-tools/index.md - Contributing to analyses: # Setting up an analysis, all the git stuff