2. Example Contribution#

2.1. Introduction#

If you’re a more experienced with the skscope and are looking forward to improve your open source development skills, the next step up is to contribute examples to skscope.

An document in example gallery is a long-form guide to shows how to use skscope to solve a sparsity-constrained optimization (SCO) problem. Typically, in this document, we will:

  • describes the problem and related practical background;

  • show readers the mathematics formulation for this problem and corresponding implementation based on skscope;

  • use either a synthetic dataset or a real-world dataset to validate the implementation. We may also compared with the benchmarked method to illustrate the advantages of SCO and skscope.

The contribution can be either:

  1. improving current examples, e.g.,

    • correcting typos

    • clarifying concepts

    • reasonably generalizing the current method to handle practical problems

    • applying it on datasets to gain new insights

or

  1. contributing a novel example that is helpful for solving meaningful problems in practice.

2.2. General Workflow#

In most of case, the workflow is based on git. But if you are not familiar with command line and git, we suggest you install the github desktop that provide a user-friendly interaction interface for simplifying documentation contribution. The instrument of “github desktop” is here.

  1. Fork the master repository by clicking on the “Fork” button on the top right of the page, which would create a copy to your own GitHub account;

  2. Clone your fork of skscope to the local computer by Git;

    git clone https://github.com/YourAccount/skscope.git
cd skscope

  1. Work on the local computer for the contribution of examples.

  2. Commit your improvements/contribution on examples:

    git add changed_files
git commit -m "YourContributionSummary"
git push

  3. Submit a pull request via Github and explain your contribution for documentation.

Next, we will give more details about step 3 to facilitate your contribution on examples.

2.3. Example Contribution Procedure#

Before contributing example, we presume that you have already complete the steps 1-2 described in general development procedure, and you have installed necessary packages by conducting the following command.

pip install -r docs/requirements.txt

There are four basic steps to contribute examples:

  1. If you going to contribute a new example, please create a new .ipynb file in the path docs/source/userguide/examples. Or, if you would like to improve a current existing example, please find the corresponding .ipynb file in the same path.

  2. Write related contents on the .ipynb files your would like to contribute.

  3. Go to the docs directory (e.g., via cd docs), and running the following command in the terminal:

    make html

This command will build web pages in your local computer. Note that, these web pages are built upon your most recent content of .ipynb files. You can preview by opening/refreshing the index.html files in docs/build/html directory.

  1. Repeat step 2 and step 3 until you are satisfied with the documentation.

After steps 1-4, you almost completely the example contribution. To ensure it also works well on the online website, please add the dependence packages in PyPI into docs/requirements.txt.