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.

Sign up for GitHub

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

Updated the contributing section #355

Merged
merged 3 commits into from
Mar 20, 2024
Merged

Updated the contributing section #355

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
937ea4a
updated the contributing section
Azaya89 Jan 30, 2024
f4c8bd8
added instructions for building site locally
Azaya89 Mar 8, 2024
907246e
post-review
Azaya89 Mar 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 95 additions & 20 deletions doc/contributing.md
View file
Open in desktop
Azaya89 marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,47 @@
You can contribute to this website either by submitting a new project
or by updating an existing one.

## Setup the managing environment
Before you submit any contribution however, you should create an `Issue` in the [project repository](https://github.com/holoviz-topics/examples)
detailing the changes you want to make to an existing example,
or the details of the new example you want to create.

## Setup

Azaya89 marked this conversation as resolved.
Show resolved Hide resolved
We **strongly recommend** you to set up the managing environment to be able
to validate and test a project locally, before submitting it to
this repository. For that, clone the repository and run:
this repository:

### Fork and Clone the repository

Create a fork of the repository and then clone your own fork via:

```bash
git clone [email protected]:<YourUsername>/holoviz-topics-examples.git
```

### Create the development environment

From the top level of your cloned directory, run:

```bash
conda env create --file envs/environment.yml
conda activate examples-gallery-manage
```

Then add the repository as your `origin` with the following commands:

<strong>SSH</strong>

```bash
git remote add origin [email protected]:holoviz-topics/examples.git
```

<strong>HTTPS</strong>

```bash
git remote add origin https://github.com/holoviz-topics/examples.git
```

## Add a project

Once you have an example (one or more notebook(s)) that you think is ready to be
Expand All @@ -27,10 +57,9 @@ re-use it as-is in multiple places.

### 2. Use the template

Copy the template project from `template/anaconda-project.yml` to
your project. You will use this file as a basis to build your
own project. You can inspect more the `template` example folder, which
contains a fully runnable and deployable project.
Copy the template project from `template/anaconda-project.yml` to your project.
You will use this file as a basis to build your own project.
You can further explore the `template` example folder, which houses a fully executable and deployable project.

```{note}
Do not forget to clean up the notes left in the template project file
Expand All @@ -57,7 +86,7 @@ build the documentation.

In some cases it is impossible for the system to execute your notebooks. This
happens for instance if your notebooks are too long to run, require too much
data, require special hardware... In those cases, you should instead commit
data, require special hardware, etc. In those cases, you should instead commit
your notebooks *with output* and set `skip_notebooks_evaluation` to `true`.

### 4. List the dependencies
Expand All @@ -78,7 +107,7 @@ to `true` in the `anaconda-project.yml`
- or, create an Intake catalog and load it in your notebooks, the catalog must be named
`catalog.yml` and be at the root of your project
- the project relies on some very light data, then it can be committed to the repository
as is, it must be stored in a `data/` subfolder of your project
as is. It must be stored in a `data/` subfolder of your project


When using an Intake catalog, point the cache to the data dir in the
Expand Down Expand Up @@ -118,17 +147,23 @@ Follow the instructions provided in the `template/anaconda-project.yml` file.

### 8. Add a thumbnail

Create a nice but lightweight PNG thumbnail, name it as your project if you have only one
notebook or as `index.png` if you have multiple notebooks, and save it in the `thumbnails`
subfolder of your project.
Create a nice but lightweight PNG thumbnail (maximum size of 1MB) with an aspect ratio between 0.9 and 1.5.
Name it as your project if you have only one notebook or as `index.png` if you have multiple notebooks,
and save it in the `thumbnails` subfolder of your project.

### 9. Locking

You must lock your project to capture the full set of dependencies that are required
to execute it. Run:
You must lock your project to capture the full set of dependencies that are required to execute it.

From your root directory, Run:

```bash
anaconda-project lock
doit lock:<projectname>
```
replacing `<projectname>` with your project name.

```{note}
All `doit` commands must be run from the root directory.
```

### 10. Make sure it works
Expand All @@ -140,12 +175,30 @@ as this is what the users of your project will ultimately use. Run:
anaconda-project run <commandname>
```

### 11. Validate, test and build
### 11. Build the site locally

You should run locally the steps that are going to be run on the CI.
Build the site locally to make sure it looks the way you expect when it is eventually deployed.

To do this:

1. Run the project notebook(s), don't clear their output.

2. Run:
```bash
doit doc_one --name <projectname>
```

This command copies the notebooks in `./doc/gallery/<projectname>` along with other files needed to build the docs (thumbnails, archive, assets, etc.), and builds the docs with Sphinx.

3. Open the built site on your web browser via: `/builtdocs/index.html`

4. Clean up this process by running `doit clean doc_one` and then commit the notebook(s) **without output.**

### 12. Validate, test, and build

After viewing the built site, you should run locally the steps that are going to be run on the CI.

Start by validating that your project is well specified by running
(replacing `<projectname>` by your project name):

```bash
doit validate:<projectname>
Expand All @@ -165,7 +218,7 @@ Update your project until the tests pass.

Run `doit clean --clean-dep test:<projectname>` to clean up that step.

Finally you will build your project running:
If you built the site locally without any errors, you can skip this final build step. However, the command to run it for debugging purposes is:

```bash
doit build:<projectname>
Expand All @@ -175,7 +228,7 @@ After validating and testing the project, this step should succeeed.

Run `doit clean --clean-dep build:<projectname>` to clean up that step.

### 12. Open a Pull Request
### 13. Open a Pull Request

Open a Pull Request that adds your project to the repository. The CI
will take care of validating, testing and building it. If these steps
Expand All @@ -188,4 +241,26 @@ the CI will also take care of automatically starting them.

## Update a project

TBD
To update an existing project, follow these simple steps.

### 1. Choose the project

Navigate to the selected project directory and execute the following command:

``` bash
anaconda-project run notebook
```

This command opens the project notebook in your web browser. If there are multiple notebooks in the project, run:

```bash
anaconda-project run <notebook name>
```

Replace `<notebook name>` with the desired notebook's name.

Remember to commit the updated notebooks **without output.**

### 2. Finalize the update

To complete the process, follow the steps outlined in [Step 11](#11.-build-the-site-locally) in the [Add a project](#add-a-project) section and continue until Step 13 which completes the process.
Loading