From 4582a32a3e3a770347bf217cb4ab1b081950dc45 Mon Sep 17 00:00:00 2001 From: Adam Li Date: Thu, 18 Jul 2024 16:33:07 -0400 Subject: [PATCH] tidy up documentation Signed-off-by: Adam Li --- CONTRIBUTING.md | 49 +++++----------------------------- DEVELOPING.md | 64 +++------------------------------------------ README.md | 20 ++++---------- doc/index.rst | 2 -- doc/installation.md | 13 +++------ 5 files changed, 18 insertions(+), 130 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a27e00840..bb016b988 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,16 +84,7 @@ When you're ready to contribute code to address an open issue, please follow the conda create -n dodiscover python=3.10 conda activate dodiscover - Next, you'll need poetry installed, which is a software dependency manager written in Python. Follow the [official instructions to install poetry](https://python-poetry.org/docs/#installation). Once your virtual environment is activated, you can install your local clone with ``poetry``. - - # the output should show a version of at least 1.2.2 (e.g. "Poetry (version 1.2.2)") - poetry --version - - # next install dodiscover using poetry - pip install -U pip setuptools wheel - poetry install --with docs,test,style --extras graph_func - - # or you can try installing in editable mode with pip + # you can try installing in editable mode with pip pip install -e . The "editable mode" comes from the `-e` argument to `pip`, and essential just creates a symbolic link from the site-packages directory of your virtual environment to the source code in your local clone. That way any changes you make will be immediately reflected in your virtual environment. @@ -130,7 +121,7 @@ When you're ready to contribute code to address an open issue, please follow the
Expand details 👇
- Our continuous integration (CI) testing runs [a number of checks](https://github.com/py-why/dodiscover/actions) for each pull request on [GitHub Actions](https://github.com/features/actions). You can run most of these tests locally, which is something you should do *before* opening a PR to help speed up the review process and make it easier for us. Please see our [development guide](https://github.com/py-why/dodiscover/blob/main/DEVELOPING.md) for a comprehensive overview of useful commands leveraging [poetry](https://python-poetry.org). This will cover aspects of code style checking, unit testing, integration testing, and building the documentation. We try to make it as easy as possible with copy/paste commands leveraging poetry which will guide your development process! + Our continuous integration (CI) testing runs [a number of checks](https://github.com/py-why/dodiscover/actions) for each pull request on [GitHub Actions](https://github.com/features/actions). You can run most of these tests locally, which is something you should do *before* opening a PR to help speed up the review process and make it easier for us. Please see our [development guide](https://github.com/py-why/dodiscover/blob/main/DEVELOPING.md). This will cover aspects of code style checking, unit testing, integration testing, and building the documentation. And finally, please update the CHANGELOG file in the [changelog folder](https://github.com/py-why/dodiscover/docs/whats_new/) with notes on your contribution in the latest version file. @@ -146,44 +137,16 @@ When you're ready to contribute code to address an open issue, please follow the We use [Sphinx](https://www.sphinx-doc.org/en/master/index.html) to build our API docs, which automatically parses all docstrings of public classes and methods. All docstrings should adhere to the [Numpy styling convention](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html). -### Testing Changes Locally With Poetry -With poetry installed, we have included a few convenience functions to check your code. These checks must pass and will be checked by the PR's continuous integration services. You can install the various different developer dependencies with poetry: - - poetry install --with style, docs, test - -You can verify that your code will pass certain style, formatting and lint checks by running: - - poetry run poe verify - -``verify`` runs a sequence of tests that can also be run individually. For example, you can check code formatting with black: - - poetry run poe format_check - -If you would like to automatically black format your changes: +### Testing Changes Locally +With pre-commit, we run various linters. - poetry run poe format - -You can then check for code style and general linting: - - poetry run poe lint - -Finally, you should run some mypy type checks: - - poetry run poe type_check + make pre-commit ### Documentation If you need to build the documentation locally and check for doc errors: - poetry run poe build_docs - -### Dependency Changes - -If you need to add new, or remove old dependencies, then you need to modify the ``pyproject.toml`` file and then also update the ``poetry.lock`` file, which version-controls all necessary dependencies. If you alter any dependency in the ``pyproject.toml`` file, you must run: - - poetry update - -To update the lock file. + make -C doc html --- diff --git a/DEVELOPING.md b/DEVELOPING.md index c14d3e4a3..ab6b37c2b 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -1,62 +1,6 @@ -# Requirements -* Python 3.8+ -* Poetry (`curl -sSL https://install.python-poetry.org | python - --version=1.2.2`) +# Developing in DoDiscover -For the other requirements, inspect the ``pyproject.toml`` file. If you are updated the dependencies, please run `poetry update` to update the +Writing your own learner. You simply write a class that implements the `learn_graph(data, **extra_params)`` function, which +will take in a dataframe and return a graph. -# Development Tasks -There are a series of top-level tasks available through Poetry. These can each be run via - - `poetry run poe ` - -### Basic Verification -* **format** - runs the suite of formatting tools applying tools to make code compliant -* **format_check** - runs the suite of formatting tools checking for compliance -* **lint** - runs the suite of linting tools -* **typecheck** - performs static typechecking of the codebase using mypy -* **unit_test** - executes fast unit tests -* **verify** - executes the basic PR verification suite, which includes all the tasks listed above - -### Longer Verification -* **integration_test** - runs slower tests and end-to-end tests are run through this task - -### Docsite -* **build_docs** - build the API documentation site - -## Details - -Here we provide some details to understand the development process. - -### Coding Style - -For convenience ``poetry`` provides a command line interface for running all the necessary development commands: - - poetry run poe format - -This will run isort and black on the entire repository. This will auto-format the code to comply with our coding style. - -### Lint - -We use linting services to check for common errors in the code. - - poetry run poe lint - -We use flake8, bandit, codespell and pydocstyle to check for code smells, which are lines of code that can lead to unintended errors. - -### Type checking - -We use type checking to check for possible runtime errors due to mismatched types. Python is dynamically typed, so this helps us and the user catch errors that would otherwise then occur during runtime. We use mypy to perform type checking. - - poetry run poe type_check - -### Unit tests - -In order for any code to be added to the repository, we require unit tests to pass. Any new code should be accompanied by unit tests. - - poetry run poe unit_test - -### Integration tests - -Dodiscover is part of pywhy's larger ecosystem of causal inference in Python. Because of this tight integration, we also have integration tests, which make sure that any changes in dodiscover do not break or change intended workflows. - - poetry run poe integration_test +More details TBD \ No newline at end of file diff --git a/README.md b/README.md index c948f64fb..f026fc31d 100644 --- a/README.md +++ b/README.md @@ -58,16 +58,12 @@ Please consider contributing to [causal-learn](https://github.com/py-why/causal- In the future we plan on trying to integrate the two libraries. -## What is the relationship with pywhy-graphs and py-indep? +## What is the relationship with pywhy-graphs and pywhy-stats? [pywhy-graphs](https://github.com/py-why/pywhy-graphs) is the home of graph data structures and graph algorithms in PyWhy. [pywhy-stats](https://github.com/py-why/pywhy-stats) serves as a repository for implementations of (un)conditional independence tests, which can be utilized in various tasks, such as causal discovery. -# dodiscover is moving to causal-learn eventually! - -We are excited to welcome [causal-learn](https://github.com/py-why/causal-learn) to the PyWhy community. We are currently incorporating do-discover innovations into causal-learn and integrating causal-learn with other PyWhy libraries. This will occur over the course of many release cycles though. In the meantime, feel free to open up issues/PRs related to API and algorithm issues you find. - # Documentation See the [development version documentation](https://py-why.github.io/dodiscover/dev/index.html). @@ -101,15 +97,9 @@ If you already have a working installation of numpy, scipy and networkx, the eas # doesn't work until we make an official release :p pip install -U dodiscover -To install the package from github, clone the repository and then `cd` into the directory. You can then use `poetry` to install: - - poetry install +To install the package from github, clone the repository and then `cd` into the directory. You can then use `pip` to install: - # for graph functionality - poetry install --extras graph_func - - # to load datasets used in tutorials - poetry install --extras data - - # if you would like an editable install of dodiscover for dev purposes pip install -e . + + # for extra functionality for documentation, building, style checking and unit-testing + pip install .[doc, build, style, test] diff --git a/doc/index.rst b/doc/index.rst index 4e931879d..a8189f9f2 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,8 +9,6 @@ algorithms and data structures of ``networkx``. We encourage you to use the package for your causal inference research and also build on top with relevant Pull Requests. -See our examples for walk-throughs of how to use the package, or - Please refer to our :ref:`user_guide` for details on all the tools that we provide. You can also find an exhaustive list of the public API in the :ref:`api_ref`. You can also look at our numerous :ref:`examples ` diff --git a/doc/installation.md b/doc/installation.md index f254c4986..639b297f8 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,17 +1,14 @@ Installation ============ -**dodiscover** supports Python >= 3.8. +**dodiscover** supports Python >= 3.10. -## Installing with ``pip``, or ``poetry``. +## Installing with ``pip``. **dodiscover** is available [on PyPI](https://pypi.org/project/dodiscover/). Just run pip install dodiscover - # or via poetry (recommended) - poetry add dodiscover - ## Installing from source To install **dodiscover** from source, first clone [the repository](https://github.com/pywhy/dodiscover): @@ -19,10 +16,6 @@ To install **dodiscover** from source, first clone [the repository](https://gith git clone https://github.com/py-why/dodiscover.git cd dodiscover -Then run installation via poetry (recommended) - - poetry install - -or via pip +Then run installation via pip pip install -e .