Merge pull request #13 from Imageomics/update/formatting

Update Site Formatting

README.md

@@ -3,25 +3,21 @@
 Welcome to the Imageomics Guide!
 
 Just joining or starting a new project? 
-Checkout the [wiki-guide](wiki-guide) for guidance on conventions and best practices.
+Checkout the [Imageomics Guide](https://imageomics.github.io/Imageomics-guide/) for guidance on conventions and best practices.
 
-## Logos
+## About the Guide
 
-We have two versions of the logo, a [fish](logos/Imageomics_logo_fish.png) and a [butterfly](logos/Imageomics_logo_butterfly.png), which should be used for scientific posters, conference, workshop, and meeting marketing materials, etc. Choice of logo is based on user preference.
-<p align="middle">
-  <img src="https://github.com/Imageomics/internal-guidelines/assets/38985481/60ab5a86-5905-4696-9f53-2caa2b02d507" width=45%/>
-  <img src="https://github.com/Imageomics/internal-guidelines/assets/38985481/8313d701-c951-43ed-b132-70616ca3c438" width=45%/>
-</p>                                                                                                                          
+This guide started as an Institute-internal wiki, focused on providing guidance and best practices for collaborative and interdisciplinary (computer science + biology) work. Recognizing that the topics and suggestions are broadly applicable to anyone working in similar or adjacent fields, we moved the vast majority to this [guide](https://imageomics.github.io/Imageomics-guide/). To increase accessibility for those less familiar with GitHub, we generated the [web site](https://imageomics.github.io/Imageomics-guide/) from our Markdown documents (which used to be wiki pages) with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
 
+Please feel free to open an [issue](https://github.com/Imageomics/Imageomics-guide/issues) with any questions regarding the content fo this guide or if you would like to contribute to the [Glossary](https://imageomics.github.io/Imageomics-guide/wiki-guide/Glossary-for-Imageomics/) or [Helpful Tools page](https://imageomics.github.io/Imageomics-guide/wiki-guide/Helpful-Tools-for-your-Workflow/).
 
-## Templates
-
-### Hugging Face
-We have Imageomics-specific versions of Hugging Face's Dataset and Model Card templates with guidance and examples, along with some reference information for their flavor of markdown and the Imageomics grant information. 
-
-To use the [template](templates) for a new dataset or model repository on HF, just navigate to the "Model/Dataset Card" tab on your repo, select "Create Model/Dataset Card", then copy and paste the contents of the appropriate template ([Dataset Card](templates/HF_DatasetCard_Template_Imageomics.md?plain=1) or [Model Card](templates/HF_ModelCard_Template_Imageomics.md?plain=1)) into the README.md file. For more information on working with Hugging Face, see the [HF Repo Guide](wiki-guide/3.2.-Hugging-Face-Repo-Guide.md) and [HF Workflow](wiki-guide/2.2.-The-Hugging-Face-Workflow.md) entries in the Imageomics Guide.
-
-**Note:** The Dataset and Model cards have incorporated some of Hugging Face's January 2024 updates (following their [Dataset Card Overhaul](https://github.com/huggingface/huggingface_hub/commit/6dd7ee829bd1b1216663a9993c1943c29b64690a)). It doesn't appear they will be updated more and we do not currently anticipate further large updates on our end as our overall template formats have diverged, but you may nevertheless wish to check HF for extra information or tagging updates ([HF Dataset Card](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/datasetcard_template.md), [HF Model Card](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md)).
-
-### GitHub Projects
-To help you get started working with [GitHub Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects), we have an [Imageomics General Project Template](https://github.com/orgs/Imageomics/projects/31/views/1) with both a [Taskboard](https://github.com/orgs/Imageomics/projects/31/views/1) and [Table](https://github.com/orgs/Imageomics/projects/31/views/2) view initialized, along with label and milestone displays turned on. To learn more about working with GitHub Projects and how this might improve your project workflow, check out our [Guide to GitHub Projects](wiki-guide/4.1.-Guide-to-GitHub-Projects.md).
+### Testing
+To test this site locally, first clone this repository, then create an environment with `requirements.txt`
+```
+pip install -r requirements.txt
+```
+and run `mkdocs serve`:
+```
+mkdocs serve
+```
+Then the site will run at http://127.0.0.1:8000/Imageomics-guide/.

docs/index.md

@@ -1,9 +1,12 @@
-# Welcome to the Imageomics Institute!
+# Welcome to the Imageomics Institute Guide!
 
-This wiki is intended to host internal documentation, making the information needed to get started with and use institute resources readily available to all members. It will evolve continuously with the institute.
+This website hosts guides to Imageomics workflows, documentation, and general best-practices for collaborative science. We aim to provide a helpful resource for a broad base of scientists working in the field of [_imageomics_](wiki-guide/Glossary-for-Imageomics.md/#imageomics) and beyond.
+
+It houses the information needed to get started with and use institute resources readily available to all members. However, most of this guide is applicable to anyone working more broadly in the field of imageomics or adjacent fields of computer and data science, and it is tailored to help domain scientists bridging that gap.
 
 ## Highlights
-There are many pages of useful information contained in this wiki covering a range of topics from institute hardware, to repositories and archives, to a glossary of _imageomics-related_ terms.
+
+There are many pages of useful information contained in this guide covering a range of topics from project management and workflows, to repositories and archives, to a glossary of _imageomics-related_ terms for improved interdisciplinary communication.
 
 ### Just starting a project?
 Check out our guides to get your project off on the right foot!
@@ -12,7 +15,7 @@ Check out our guides to get your project off on the right foot!
 
 - [The Hugging Face Repo Guide](wiki-guide/Hugging-Face-Repo-Guide.md): Analogous expected and suggested repository contents for Hugging Face repositories; there are notable differences from GitHub in both content and structure.
 
-- [Metadata Guide](wiki-guide/Metadata-Guide.md): Guide to metadata collection and documentation. This closely follows the [HF Dataset Card Template](wiki-guide/HF_DatasetCard_Template_mkdocs.md) sections.
+- [Metadata Guide](wiki-guide/Metadata-Guide.md): Guide to metadata collection and documentation. This closely follows our [HF Dataset Card Template](wiki-guide/HF_DatasetCard_Template_mkdocs.md) sections.
 
 ### Project repo up, what's next?
 Check out our workflow guides for how to interact with your new repo:
@@ -49,9 +52,17 @@ Discover new tools to help:
 ![tech_infrastructure_diagram](wiki-guide/images/index/382108831-1173cd79-db94-4326-8b6e-dcbdeb8939cd.png)
 
 
+## Imageomics Branding (Logos)
+
+We have two versions of the logo, a [fish](logos/Imageomics_logo_fish.png) and a [butterfly](logos/Imageomics_logo_butterfly.png), which should be used for scientific posters, conference, workshop, and meeting marketing materials, etc. Choice of logo is based on user preference.
+
+![butterfly logo](logos/Imageomics_logo_butterfly.png){: style="width:45%"}
+![fish logo](logos/Imageomics_logo_fish.png){: style="width:45%"}
+
+
 ## Other pages of note
 - [Glossary for Imageomics](wiki-guide/Glossary-for-Imageomics.md): Collection of terms used in imageomics. The goal is to ensure all participating domains are represented, thus facilitating interdisciplinary communication. This is a group effort, please check it out and add terms you think should be there!
-- [Command Line Cheat Sheet](wiki-guide/Command-Line-Cheat-Sheet.md): Collection of useful bash, emacs, and git commands.
+- [Command Line Cheat Sheet](wiki-guide/Command-Line-Cheat-Sheet.md): Collection of useful bash and git commands with some git tips.
 
 
 <br>

docs/wiki-guide/About-Templates.md

@@ -0,0 +1,15 @@
+# Using Dataset and Model Card Templates
+
+We have Imageomics-specific versions of Hugging Face's Dataset and Model Card templates. These include guidance and examples for the various metadata sections, reference information for Hugging Face's particular flavor of markdown, and the Imageomics grant acknowledgment. 
+
+To use the template for a new dataset or model repository on Hugging Face (HF), simply copy and paste the contents of the appropriate template ([Dataset Card](HF_DatasetCard_Template_mkdocs.md) or [Model Card](HF_ModelCard_Template_mkdocs.md)) into your `README.md` file.[^1] 
+Then, follow the descriptions under each section to fill in the appropriate information. This is meant to be an iterative process throughout the life of your project, so do not worry if you cannot answer all parts at the beginning—that's to be expected!
+[^1]: The templates can also be added to your repository thorugh the website user interface (UI): Navigate to the "Model/Dataset Card" tab on your repo, select "Create Model/Dataset Card", copy and paste the template contents into the `README.md` file, and add your content.
+
+
+!!! tip "Practice makes perfect!"
+    If you have never filled out a dataset card before, or are unsure of how to find the answers to fill in the sections, we ran a [workshop](https://github.com/Imageomics/data-workshop-AH-2024) to help familiarize our members with this process. In particular, the portion where we walked through filling out part of a dataset card as we did exploratory data analysis (EDA) was recorded and is available on the [Imageomics YouTube Channel](https://www.youtube.com/@ImageomicsInstitute/videos). Read the [story of the workshop](https://github.com/Imageomics/data-workshop-AH-2024/#story-of-the-workshop) and clone the [repo](https://github.com/Imageomics/data-workshop-AH-2024) to follow along with the 1 hour and 15 minute lesson!
+
+!!! note "Note"
+    The Dataset and Model cards have incorporated some of Hugging Face's January 2024 updates (following their [Dataset Card Overhaul](https://github.com/huggingface/huggingface_hub/commit/6dd7ee829bd1b1216663a9993c1943c29b64690a)). It doesn't appear they will be updated more and we do not currently anticipate further large updates on our end as our overall template formats have diverged, but you may nevertheless wish to check HF for extra information or tagging updates ([HF Dataset Card](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/datasetcard_template.md), [HF Model Card](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md)).
+

docs/wiki-guide/Command-Line-Cheat-Sheet.md

@@ -12,9 +12,9 @@ See also [GitHub's Markdown Guide](https://docs.github.com/en/get-started/writin
 | `ls` | 		list everything in current directory (use `-a` to also show **a**ll files including hidden, `-l` for a **l**ong list including permissions and ownership info, `-1` ("dash one") to display the output with **1** item on each line) |
 | `wc -l <file>` |      use the **w**ord **c**ount command with the `-l` **l**ines option to list the number of lines in a file |
 | `du <dirname>/`|      calculate and show how much **d**isk **u**sage is consumed by a directory (use `-h` to make it **h**uman-readable, i.e. report in MB, GB or whatever units are most appropriate, and `-s` for **s**ummary of all the contents together rather than each item individually) |        
-| `ctrl r` |		search for command (will pop up `bck-i-search:`) |
+| ++ctrl+r++ |		search for command (will pop up `bck-i-search:`) |
 | `rm <target>` |       remove a file (or folder with `-r`). Beware when using `rm -rf <folder>` to **f**orce the **r**ecursive removal of all contents in a folder, which cannot be undone unless there is a backup. |
-| `<cmd1> \| <cmd2>` |   The "pipe" operator (`\|`) feeds the output of the first command (`cmd1`) to the input of the second command (`cmd2`). For example, show the total number of files in a directory with `ls -1 <dir> \| wc -l`|
+| `<cmd1> | <cmd2>` |   The "pipe" operator (++pipe++) feeds the output of the first command (`cmd1`) to the input of the second command (`cmd2`). For example, show the total number of files in a directory with `ls -1 <dir> | wc -l`|
 
 ### Git-Specific
 | Command | Action |

docs/wiki-guide/GitHub-Repo-Guide.md

@@ -210,4 +210,4 @@ If you would like a specific branch, use `git clone -b <branch_name> <repo_url>`
 ## Workflow Summary
 Generally, repositories are organized around an Imageomics Project/Topic/Team, eg., butterflies. These broader topics may contain various projects organized under a GitHub [Team](https://github.com/orgs/Imageomics/teams) focused on that topic. Both [projects](https://github.com/orgs/Imageomics/projects?query=is%3Aopen) and [repositories](https://github.com/orgs/Imageomics/repositories) may be linked to teams, providing an organizational structure upon which to plan and manage tasks while maintaining a clear link/connection to the work being done on those tasks. Note that a project may encapsulate multiple repositories just as a repository may be referenced by multiple projects.
 
-Ideally, each task will be linked to an issue in the relevant repository. Team members may then be assigned tasks, and asynchronous discussions about the task can be recorded on its issue page in the repository. To accomplish the task, a new branch should be created following the [branch naming conventions](#formatting-and-naming-conventions); do not work directly on the `main` branch. Once the task is completed, a pull request can be opened to merge the changes into the main branch (see the [GitHub Workflow Guide](The-GitHub-Workflow.md) and the [PR Guide](The-GitHub-Pull-Request-(PR)-Guide.md) for more details on this process). Reviewers may be assigned to each pull request to ensure compatibility and that the proposed solution functions as expected/needed; this is an opportunity for more dialogue. 
+Ideally, each task will be linked to an issue in the relevant repository. Team members may then be assigned tasks, and asynchronous discussions about the task can be recorded on its issue page in the repository. To accomplish the task, a new branch should be created following the [branch naming conventions](#formatting-and-naming-conventions); do not work directly on the `main` branch. Once the task is completed, a pull request can be opened to merge the changes into the main branch (see the [GitHub Workflow Guide](The-GitHub-Workflow.md) and the [PR Guide](The-GitHub-Pull-Request-Guide.md) for more details on this process). Reviewers may be assigned to each pull request to ensure compatibility and that the proposed solution functions as expected/needed; this is an opportunity for more dialogue. 

docs/wiki-guide/Guide-to-GitHub-Projects.md

@@ -9,9 +9,15 @@ When starting a new project, it can be helpful to have a shared tracker or proje
     - Clicking on an assignees profile image will show only that person's assigned tasks (similarly for labels and milestones attached to tasks).
  - More columns/categories can be added for different aspects of the project.
  - Multiple repos can be linked to a single project.
+    - Access to issues _is_ controlled by repo access permissions; only the existence of issues is universal to the project.
  - Closing an issue will automatically move the task to "Done".
  - Tasks can be reordered within their columns/categories to keep most pressing tasks at the top.
 
 ## Interacting with GitHub Projects
-To help you get started working with [GitHub Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects), we have an [Imageomics General Project Template](https://github.com/orgs/Imageomics/projects/31/views/1) with both a [Taskboard](https://github.com/orgs/Imageomics/projects/31/views/1) and [Table](https://github.com/orgs/Imageomics/projects/31/views/2) view initialized, along with label and milestone displays turned on. 
-Both of these views will automatically stay updated so that each member of the project can utilize whichever version they find most informative. Issues can be added directly to the project board/table or on the repo (if added on the repo, they must be linked to the project, and have status assigned). Milestones must be created on the repo (under the Issues tab, select "Milestones" to create one).
+To help you get started working with [GitHub Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects), we have a [General Project Template](https://github.com/orgs/Imageomics/projects/31/views/1) with both a [Taskboard](https://github.com/orgs/Imageomics/projects/31/views/1) and [Table](https://github.com/orgs/Imageomics/projects/31/views/2) view initialized, along with label and milestone displays turned on. 
+Both of these views will automatically stay updated so that each member of the project can utilize whichever version they find most informative. 
+
+Issues can be added directly to the project board/table or on the repo. If added through the repo, they must be linked to the project and have status assigned. Milestones must be created on the repo (under the Issues tab, select "Milestones" to create one), similarly for labels. 
+
+!!! note "Note"
+    Issues on a project board that are linked to a repository to which a user does not have access will not be visible to them, even if they have access to the project. They will show up (for that user) as unidentified issues with no status.

docs/wiki-guide/Hugging-Face-Repo-Guide.md

@@ -71,4 +71,4 @@ git push origin pr/<PR#>:refs/pr/<PR#>
 For more information on Hugging Face Pull Requests and Discussions, see their [documentation](https://huggingface.co/docs/hub/repositories-pull-requests-discussions).
 
 ## Templates for Model and Dataset Cards
-See [here](https://github.com/Imageomics/Imageomics-Guide#hugging-face) for guidelines on using templates for these important pieces of documentation.
+See [About Templates](About-Templates.md) for guidelines on using templates for these important pieces of documentation.

docs/wiki-guide/Metadata-Guide.md

@@ -1,6 +1,6 @@
 # Metadata Guide
 
-When collecting or compiling new data, there are generally questions one is _trying_ to answer. There are also often questions that will come up later--whether for yourself or others interested in using your data. 
+When collecting or compiling new data, there are generally questions one is _trying_ to answer. There are also often questions that will come up later—whether for yourself or others interested in using your data. 
 
 To improve both the _**Findability**_ and _**Reusability**_ of your data (ensuring [FAIR principles](Glossary-for-Imageomics.md#fair-data-principles)) for yourself and others, be sure to note down the following information.