Skip to content

Commit

Permalink
Merge pull request #987 from microsoft/dev
Browse files Browse the repository at this point in the history 
Dev into main for 2.0.0
  • Loading branch information
@daxpryce
daxpryce authored Sep 16, 2022
2 parents e5ed9ad + d5ef3b1 commit f9fb042
Show file tree
Hide file tree
Showing 40 changed files with 2,280 additions and 1,478 deletions.
210 changes: 117 additions & 93 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,7 @@ to see a feature implemented. Please also feel free to tag one of the core
contributors (see our [Roles page](https://github.com/microsoft/graspologic/blob/dev/ROLES.md)).

In case you experience issues using this package, do not hesitate to submit a ticket to our
[Issue Tracker](https://github.com/microsoft/graspologic/issues). You are also welcome to post feature requests or pull
requests.
[Issue Tracker](https://github.com/microsoft/graspologic/issues). You are also welcome to post feature requests or pull requests.

It is recommended to check that your issue complies with the following rules before submitting:

Expand Down Expand Up @@ -61,18 +60,18 @@ follow these guidelines! This will make it a lot faster for us to respond to you
[Creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks)
for more details.

# Contributing Code
# Contributing code

## Git workflow
## Setting up for development

The preferred workflow for contributing to Graspologic is to fork the main repository on GitHub, clone, and develop on a
branch. Steps:
The preferred workflow for contributing to `graspologic` is to fork the main repository on GitHub, clone, and develop on a
branch using a virtual environment. Steps:

1. Fork the [project repository](https://github.com/microsoft/graspologic) by clicking on the ‘Fork’ button near the top
right of the page. This creates a copy of the code under your GitHub user account. For more details on how to
fork a repository see [this guide](https://help.github.com/articles/fork-a-repo/).

2. Clone your fork of the Graspologic repo from your GitHub account to your local disk:
2. Clone your fork of the `graspologic` repo from your GitHub account to your local disk:

```bash
git clone git@github.com:YourGithubAccount/graspologic.git
Expand All @@ -88,43 +87,8 @@ branch. Steps:
Always use a `feature` branch. Pull requests directly to either `dev` or `main` will be rejected
until you create a feature branch based on `dev`.

4. Unit testing

It's important to write unit tests for your bug fix and your features. When fixing a bug, first create a test that explicitly exercises the bug and results in a test case failure. Then create the fix and run the test again to verify your results.

For new features, we advocate using [TDD](https://en.wikipedia.org/wiki/Test-driven_development) wherever possible.

We also explicitly ask that you hew toward the `unittest` Python module for conformance. This will ensure it plays nicely with most common IDEs on the market.

5. Code formatting:
It's important to us that you follow the standards of our project. Please use `black` and `isort` prior to
committing.

```bash
# Run "black" and "isort" using Make
make format
```
OR
```bash
black graspologic/ tests/
isort graspologic/ tests/
```

6. Develop the feature on your feature branch. Add changed files using `git add` and then `git commit` files:

```bash
git add modified_files
git commit
```

After making all local changes, you will want to push your changes to your fork:
```bash
git push -u origin my-feature
```

## Local Developer Setup
1. Make sure you have a compatible version of Python 3 installed
2. From the project root, create a virtual environment and install all development dependencies. This example uses Python 3.8 but you may use any Python version supported by graspologic.
4. From the project root, create a [virtual environment](https://docs.python.org/3/library/venv.html) and install all development dependencies. Examples using various terminals are provided below. These examples use Python 3.8 but you may use any Python version supported by graspologic. These commands should install `graspologic` in editable mode, as well as
all of its dependencies and several tools you need for developing `graspologic`.

**Bash**
```bash
Expand Down Expand Up @@ -162,58 +126,118 @@ branch. Steps:
pip install -U pip setuptools
pip install -r requirements.txt
```
3. Start playing with Graspologic code!

## Pull Request Checklist
## Code Changes

### Writing Code
- Make sure to follow the coding guidelines outlined below:
- Uniformly formatted code makes it easier to share code ownership. Graspologic package closely follows the official Python guidelines detailed in [PEP8](https://www.python.org/dev/peps/pep-0008/) that detail how code should be formatted and indented. Please read it and follow it.
- In order to make sure all code is formatted seamlessly and uniformly, we use [black](https://github.com/psf/black) to automatically format our code.
- All new functions should have PEP-compliant type hints and [@beartype](https://github.com/beartype/beartype) decorator. This allows us a reasonable level of confidence that arguments passed into the API are what we expect them to be without sacrificing runtime speed.
- All public methods should have informative [`docstrings`](https://github.com/microsoft/graspologic/blob/dev/CONTRIBUTING.md#docstring-guidelines) with sample usage presented as doctests when appropriate.
- Properly formatted docstrings are required for documentation generation by [sphinx](https://www.sphinx-doc.org/en/master/usage/index.html). The graspologic package closely
follows the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html#overview) guidelines. Please read and follow the
numpydoc guidelines. Refer to the
[example.py](https://numpydoc.readthedocs.io/en/latest/example.html#example) provided by numpydoc.
- If proposing a new method, include at least one paragraph of narrative documentation with links to references in the literature (with PDF links when possible) and the example.
- If your feature is complex enough, consider creating a Jupyter notebook tutorial to illustrate its use instead. Tutorial Jupyter notebooks can be added to the docs [here](https://github.com/microsoft/graspologic/tree/dev/docs/tutorials).
- All functions and classes should be rigorously typed with Python 3.5+ [`typehinting`](https://docs.python.org/3/library/typing.html).
- All functions and classes must have unit tests. These should include, at the very least, type checking and ensuring correct computation/outputs.

- It's important to write unit tests for your bug fix and your features. When fixing a bug, first create a test that explicitly exercises the bug and results in a test case failure. Then create the fix and run the test again to verify your results.

- For new features, we advocate using [TDD](https://en.wikipedia.org/wiki/Test-driven_development) wherever possible.

### Checking code

After you have made changes to the `graspologic` code, you should use several
tools to help make sure your changes meet the standards for our repository.

#### Code formatting
Please use `black` and `isort` so that the format of your code is compatible with our project. Format your code prior to committing using one of the following methods:
```bash
# Run "black" and "isort" using Make
make format
```
OR
```bash
# Run "black" and "isort"
black graspologic/ tests/
isort graspologic/ tests/
```

#### Type checking
Validate your typehinting by running:
```bash
make type-check
```
OR
```bash
mypy ./graspologic
```

#### Unit testing
To check if your code runs correctly, we recommend using unit testing that locally tests your code by implementing test cases. Execute these unit tests by running:
```bash
make test
```
OR
```bash
pytest tests
```

#### Creating documentation
Build the documentation with the use of [sphinx](https://www.sphinx-doc.org/en/master/usage/index.html) by running:
```bash
make docs
```
OR
```bash
sphinx-build -W -t build_tutorials -a docs/ docs/_build/html
```
Please verify that the built documentation looks appropriate. You can view the `html`
from the `docs/_build/html` folder; click on `index.html` to see what the homepage would
look like and navigate from there.

If you have made any changes that could affect the tutorials, please also build them.
This can take a bit longer because the code in each notebook actually needs to execute.
You can build the documentation and tutorials by running:
```bash
make docsWithTutorials
```
OR
```bash
sphinx-build -W -t build_tutorials -a docs/ docs/_build/html
```

## Publishing Changes

### Useful Git Commands
When working on a new feature, develop the feature on your feature branch. Add changed files using `git add` and then `git commit` files:

```bash
git add modified_files
git commit -m "your commit message"
```

After making all local changes, you will want to push your changes to your fork:
```bash
git push -u origin my-feature
```

### Creating a pull request

We recommended that your contribution complies with the following rules before you submit a pull request:
We recommend that your pull request complies with the following rules before it is submitted:

- Follow the [coding-guidelines](#guidelines).
- Give your pull request (PR) a helpful title that summarizes what your contribution does. We are using PR titles to automatically generate release notes; examples of helpful PR title formats include:
- Make sure that the base repository and head repository, as well as the "base" file and "compare" file, are pointing to the correct locations
- Give your pull request (PR) a helpful title, set in the past tense, that summarizes what your contribution does. We are using PR titles to automatically generate release notes; examples of helpful PR title formats include:
- `Added Feature[Set] {Title|Short Descriptor} in ModuleOrPackageName`
- `Fixed bug in [ClassName.method_name|ModuleOrPackageName.function_name] where ShortDescription`
- `Updated [ClassName[.method_name]|ModuleOrPackageName.function_name] to ShortDescription`
- Link your pull request to the issue (see:
[closing keywords](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue)
for an easy way of linking your issue)
- All public methods should have informative docstrings with sample usage presented as doctests when appropriate.
- At least one paragraph of narrative documentation with links to references in the literature (with PDF links when
possible) and the example.
- If your feature is complex enough that a doctest is insufficient to fully showcase the utility, consider creating a
Jupyter notebook to illustrate use instead
- All functions and classes must have unit tests. These should include, at the very least, type checking and ensuring
correct computation/outputs.
- All functions and classes should be rigorously typed with Python 3.5+
[`typehinting`](https://docs.python.org/3/library/typing.html). Validate your typehinting by running `mypy ./graspologic`
- All code should be automatically formatted by `black`. You can run this formatter by calling:
```bash
pip install black isort
black path/to/your_module.py
isort path/to/your_module.py
```
- Ensure all tests are passing locally using `pytest`. Install the necessary
packages by:

```bash
pip install pytest pytest-cov
pytest
```

# Guidelines

## Coding Guidelines

Uniformly formatted code makes it easier to share code ownership. Graspologic package closely follows the official
Python guidelines detailed in [PEP8](https://www.python.org/dev/peps/pep-0008/) that detail how code should be
formatted and indented. Please read it and follow it.

All new functions should have PEP-compliant type hints and "@beartype" annotations. This allows us a reasonable level
of confidence that arguments passed into the API are what we expect them to be without sacrificing runtime speed. See
https://github.com/beartype/beartype for more information.

## Docstring Guidelines

Properly formatted docstrings are required for documentation generation by Sphinx. The graspologic package closely
follows the numpydoc guidelines. Please read and follow the
[numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html#overview) guidelines. Refer to the
[example.py](https://numpydoc.readthedocs.io/en/latest/example.html#example) provided by numpydoc.
- Link your pull request to the issue (see: [closing keywords](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue) for an easy way of linking your issue)
- Include a brief description of the changes you made in the code in the "write" box provided in the pull request page

Once submitted, your PR will undergo automated tests that ensure its compilability and compatibility with our project. For debugging tests that raise errors online but passed locally, one can look at [this file](https://github.com/microsoft/graspologic/blob/dev/.github/workflows/build.yml) to see Github's exact execution.



20 changes: 14 additions & 6 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
import os
import sys

sys.path.append(os.path.abspath('./sphinx-ext/'))
sys.path.append(os.path.abspath("./sphinx-ext/"))
sys.path.insert(0, os.path.abspath(".."))

# -- Project information -----------------------------------------------------
Expand Down Expand Up @@ -78,20 +78,28 @@
"anytree": ("https://anytree.readthedocs.io/en/latest/", None),
"hyppo": ("https://hyppo.neurodata.io", None),
"joblib": ("https://joblib.readthedocs.io/en/latest/", None),
"matplotlib": ("https://matplotlib.org", None),
"matplotlib": ("https://matplotlib.org/stable/", None),
"networkx": ("https://networkx.org/documentation/stable", None),
"numpy": ("https://numpy.org/doc/stable", None),
"numpy": ("https://matplotlib.org/stable/", None),
"pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
"python": ("https://docs.python.org/3.9", None),
"scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
"scipy": ("https://docs.scipy.org/doc/scipy", None),
"seaborn": ("https://seaborn.pydata.org", None),
"sklearn": ("https://scikit-learn.org/dev", None),
}

intersphinx_disabled_reftypes = []

# -- sphinx options ----------------------------------------------------------
source_suffix = ".rst"
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints", "tutorials"]
toc_filter_exclude = ['tutorials/index']
exclude_patterns = [
"_build",
"Thumbs.db",
".DS_Store",
"**.ipynb_checkpoints",
"tutorials",
]
toc_filter_exclude = ["tutorials/index"]
master_doc = "index"
source_encoding = "utf-8"
if tags.has("build_tutorials"):
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/reference/match.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ Matching

Graph Matching
--------------------
.. autoclass:: GraphMatch
.. autofunction:: graph_match
5 changes: 5 additions & 0 deletions docs/reference/reference/models.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,8 @@ Latent position models
----------------------

.. autoclass:: RDPGEstimator

Edge swapping (configuration models)
------------------------------------

.. autoclass:: EdgeSwapper
37 changes: 37 additions & 0 deletions docs/reference/release.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,43 @@
Release Log
===========

graspologic 2.0.0
-----------------
- Refactored graph matching code and added many new features
`#960 <https://github.com/microsoft/graspologic/pull/960>`
- Added elbow marker to screeplot in plot module
`#979 <https://github.com/microsoft/graspologic/pull/979>`
- Fixed mug2vec behavior for directed graphs
`#968 <https://github.com/microsoft/graspologic/pull/968>`
- Fixed typo in aligning tutorial
`#974 <https://github.com/microsoft/graspologic/pull/974>`
- Added sex labels to mice dataset
`#967 <https://github.com/microsoft/graspologic/pull/967>`
- Made improvements to contributing guidelines
`#973 <https://github.com/microsoft/graspologic/pull/973>`
- Corrected notation in documentation of to_laplacians
`#969 <https://github.com/microsoft/graspologic/pull/969>`
- Fixed isolated nodes handling in node2vec
`#953 <https://github.com/microsoft/graspologic/pull/953>`
- Fixed repeated numba compilation in EdgeSwapper
`#965 <https://github.com/microsoft/graspologic/pull/965>`
- Fixed intersphinx bug
`#963 <https://github.com/microsoft/graspologic/pull/963>`
- Removed default axis labels in networkplot
`#954 <https://github.com/microsoft/graspologic/pull/954>`
- Fixed reproducibility in EdgeSwapper and added to docs
`#945 <https://github.com/microsoft/graspologic/pull/945>`
- Added Degree Preserving Edge Swaps
`#935 <https://github.com/microsoft/graspologic/pull/935>`
- Fixed mypy issue
`#943 <https://github.com/microsoft/graspologic/pull/943>`
- Fixed loops bug in SBM and DCSBM model fitting
`#930 <https://github.com/microsoft/graspologic/pull/930>`
- Added error message in Leiden when given a multigraph was incorrect
`#926 <https://github.com/microsoft/graspologic/pull/926>`
- Fixed typos in ER and SBM models
`#920 <https://github.com/microsoft/graspologic/pull/920>`

graspologic 1.0.0
-----------------
- Removed Python 3.6 support
Expand Down
Loading

0 comments on commit f9fb042

Please sign in to comment.