Contribution Guide for NX-Guides

CONTRIBUTING.md

Contributor Guide

• This document assumes some familiarity NetworkX library and contributing to open source scientific Python projects using Github pull requests. If this does not describe you, you may first want to see the Contributing FAQs.
• Building and Testing process of this project is done on Linux and MacOS platforms. Therefore, any one of the afformentioned platforms is an extra requirement for this project.

Development Workflow

Project setup

If you are a first time contributor:

• Go to https://github.com/networkx/nx-guides and click on the fork button to create your own copy of the project.
• Clone the project to your local system

   git clone https://github.com/username/nx-guides.git
  

• Navigate to the folder and add upstream repository:

  git remote add upstream git@github.com:networkx/nx-guides.git
  

• Now you will have remote repositories named as such:
  • upstream, refering to the nx-guides repository
  • origin, refering to your personal forked repository
• Next, you need to set up your build environment. Here are the instructions for two popular environment managers:
  • venv (pip based)

    # Create a virtualenv named ``nx-guides-dev``
    python -m venv nx-guides-dev
    # Activate it
    source nx-guides-dev/bin/activate
    # Install main development and runtime dependencies
    pip install -r requirements.txt

  • conda (Anaconda or Miniconda)

    # Create a conda environment named ``nx-guides-dev``
    conda create --name nx-guides-dev
    # Activate it
    conda activate nx-guides-dev
    # Install main development and runtime dependencies
    conda install -c conda-forge --file requirements.txt

2. Develop your contribution
   • Pull the latest changes from upstream

     git checkout main
     git pull upstream main
     

   • Create a branch for the feature you want to work on. Since the branch name will appear in the merge message, use a sensible name such as 'bugfix-for-issue-1480':

     git checkout -b bugfix-for-issue-1480
     

   • Commit locally using git add and git commit as you progress

Working on a Notebook

After you have created the Jupyter Notebook on your selected algorithm or networkx application (Guidelines for appropriate notebooks), the next step would be converting the notebook. The educational materials in the form of markdown-based Jupyter Notebooks which makes them interactive! You can follow along yourself:

1. on binder, by clicking on the launch button at the top of this page, or the rocket icon in the upper-right corner of any of the pages, or
2. locally, by cloning the repository (see the octocat icon above) and running jupyter notebook.

To convert a notebook into markdown format, jupytext is used. The following command is used for the conversion:

jupytext notebook.ipynb --to myst   

After conversion, the next task would be arranging the files in the correct location. For maintaining a consistent coding style, the following rules are to followed -

1. The .md file generated will be placed in a subdirectory under appropriate directory
2. Only a single .md file will be stored in a directory. For multiple files, multiple directories should be created accordingly. These directories should be then arranged properly for a tree structure. See Algorithms.
3. Markdown file generated using Jupytext are to named index.md
4. All the datasets used in the notebooks should be placed in an data folder
5. All the static images used for the documentation should be placed in images folder
6. Each index.md is to be mentioned in the parent directory's TOC tree. Finally, the .md file in main directory of /content should be included in TOC tree of /site/index.md.

Build Process of Project