restructure contributing docs

OriolAbril · OriolAbril · commit 6caabff3b3a3 · 2021-11-24T04:42:08.000+02:00
diff --git a/docs/source/about/citing_pymc.md b/docs/source/about/citing_pymc.md
@@ -1,18 +1,20 @@
 (citing_pymc)=
 # Citing PyMC
 
+TODO: extend advise, copy info from readme, explain citing paper plus specific zenodo version...
+
 If you use PyMC in your reseach please cite: Salvatier J., Wiecki T.V., Fonnesbeck C. (2016) Probabilistic programming in Python using PyMC. PeerJ Computer Science 2:e55 [DOI: 10.7717/peerj-cs.55](https://doi.org/10.7717/peerj-cs.55).
 
 The BibTeX entry is:
 
-.. code-block:: none
-
-    @article{pymc,
-      title={Probabilistic programming in Python using PyMC3},
-      author={Salvatier, John and Wiecki, Thomas V and Fonnesbeck, Christopher},
-      journal={PeerJ Computer Science},
-      volume={2},
-      pages={e55},
-      year={2016},
-      publisher={PeerJ Inc.}
-    }
+```bibtex
+@article{pymc,
+  title={Probabilistic programming in Python using PyMC3},
+  author={Salvatier, John and Wiecki, Thomas V and Fonnesbeck, Christopher},
+  journal={PeerJ Computer Science},
+  volume={2},
+  pages={e55},
+  year={2016},
+  publisher={PeerJ Inc.}
+}
+```
diff --git a/docs/source/about/featured_testimonials.md b/docs/source/about/featured_testimonials.md
@@ -0,0 +1,48 @@
+:::{card}
+:class-body: small
+:link: https://www.spacex.com/
+
+**SpaceX**
+^^^
+> At SpaceX PyMC helped us estimate supplier delivery uncertainty and quantify which suppliers were consistent in sending us rocket parts and which suppliers we needed to partner with to understand how we could reduce variability
+
+_Ravin Kumar_
+:::
+
+:::{card}
+:class-body: small
+:link: https://www.salesforce.com
+
+**Salesforce**
+^^^
+> PyMC is my primary tool for statistical modeling at Salesforce. I use it to combine disparate sources of information and pretty much anywhere that quantifying uncertainty is important. We've also been experimenting with gaussian processes to model time series data for forecasting.
+
+_Eddie Landesberg. Manager, Data Scientist_
+:::
+
+:::{card}
+:class-body: small
+**[Novartis Institutes for Biomedical Research](https://www.novartis.com/our-science/novartis-institutes-biomedical-research)**
+^^^
+> At the Novartis Institutes for Biomedical Research, we use PyMC for a wide variety of scientific and business use cases. The API is incredible, making it easy to express probabilistic models of our scientific experimental data and business processes, such as models of electrophysiology and molecular dose response.
+
+_Eric J. Ma_
+:::
+
+:::{card}
+:class-body: small
+**[Intercom](https://www.intercom.com)**
+^^^
+> At Intercom, we've adopted PyMC as part of our A/B testing framework. The API made it easy to integrate into our existing experimentation framework and the methodology has made communication of experiment results much more straightforward for non technical stakeholders.
+
+_Louis Ryan_
+:::
+
+:::{card}
+:class-body: small
+**[Channel 4](http://www.channel4.co.uk)**
+^^^
+> Used in research code at Channel 4 for developing internal forecasting tools.
+
+_Peader Coyle_
+:::
diff --git a/docs/source/about/index.md b/docs/source/about/index.md
@@ -34,4 +34,5 @@ PyMC strives to make Bayesian modeling as simple and painless as possible,  allo
 citing_pymc
 history_and_versions
 pymc_for_enterprise
+testimonials
 :::
diff --git a/docs/source/about/testimonials.md b/docs/source/about/testimonials.md
@@ -0,0 +1,4 @@
+(testimonials)=
+# Testimonials
+
+TODO: move testimonials from wiki to here
diff --git a/docs/source/community.md b/docs/source/community.md
@@ -11,7 +11,8 @@ Discourse is the best place to interact with the PyMC community and its team
 
 ## Conferences
 
-[PyMCon](https://pymc-devs.github.io/pymcon/) was a conference organized by the PyMC developer community in 2020.
+The PyMC community organizes [PyMCon](https://pymc-devs.github.io/pymcon/), whose last edition was in 2020.
+Follow Discourse or Twitter to be updated about the next edition!
 
 PyMC talks have been given at a number of conferences, including [PyCon](https://us.pycon.org/),
 [PyData](https://pydata.org/events/), and [ODSC](https://odsc.com/) events.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -110,11 +110,16 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build", "**.ipynb_checkpoints", "pymc-examples/.github"]
+exclude_patterns = [
+    "_build",
+    "**.ipynb_checkpoints",
+    "pymc-examples/.github",
+    "about/featured_testimonials.md",
+]
 
 # myst and panels config
 jupyter_execute_notebooks = "off"
-myst_enable_extensions = ["colon_fence", "deflist", "dollarmath", "amsmath"]
+myst_enable_extensions = ["colon_fence", "deflist", "dollarmath", "amsmath", "substitution"]
 panels_add_bootstrap_css = False
 
 # The reST default role (used for this markup: `text`) to use for all
@@ -227,7 +232,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static", "nb_tutorials/_images", "nb_examples/_images"]
+# html_static_path = ["_static", "nb_tutorials/_images", "nb_examples/_images"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
diff --git a/docs/source/contributing/build_docs.md b/docs/source/contributing/build_docs.md
@@ -0,0 +1,14 @@
+# Build documentation locally
+
+To build the docs, run these commands at pymc repository root:
+
+TODO: fix makefile
+
+```bash
+$ pip install -r requirements-dev.txt  # Make sure the dev requirements are installed
+$ cd docs/source
+$ make html  # Build docs
+$ python -m http.server --directory ../_build/html  # Render docs
+```
+
+Check the printed url where docs are being served and open it.
diff --git a/docs/source/contributing/developer_guide_implementing_distribution.md b/docs/source/contributing/developer_guide_implementing_distribution.md
@@ -1,4 +1,4 @@
-# Implementing a Distribution (developer guide)
+# Implementing a Distribution
 
 This guide provides an overview on how to implement a distribution for version 4 of PyMC.
 It is designed for developers who wish to add a new distribution to the library.
diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md
@@ -1,30 +1,57 @@
 # Contributing
 
-PyMC is an open source, collective effort. There are many ways in which you can help make it better.
-
-## Help develop PyMC
+PyMC is an open source, collective effort.
+There are many ways in which you can help make it better.
+And all of them are welcome!
+
+## Contribute as an individual
+PyMC is a joint effort of many people, each contributing to the areas they like
+and have some expertise in, coordinating to try and cover all tasks.
+
+Coding and documentation are the most common types of contributions, but
+there are many more things that you can do to help PyMC which are just as
+important. Moreover, both code and docs require submitting PRs via GitHub
+to some of the repositories under the [pymc-devs](https://github.com/pymc-devs) organization, and
+while we have a {ref}`pr_tutorial` guide available, GitHub might not be
+everyone's cup of tea. If that is your case, don't worry, you will be
+more than welcome if you want to help.
+
+:::{tip}
+Contact us on [Discourse](https://discourse.pymc.io/) if you want to contribute to the project but are not sure where you can contribute or how to start
+:::
 
-Learn about developing PyMC in our Developer's section.
+Below there are some examples of non code nor doc contributions that could serve as an inspiration.
+If you have other ideas let us know on [Discourse](https://discourse.pymc.io/) to see if we can make it happen too.
 
-Report a bug or make a suggestion for improvement by [opening an issue in Github](https://github.com/pymc-devs/pymc/issues/new/choose)
+* Report a bug or make a suggestion for improvement by [opening an issue in Github](https://github.com/pymc-devs/pymc/issues/new/choose)
+* Answer questions on [Discourse](https://discourse.pymc.io/)
+* Teach about PyMC and advertise best practices by writing blogs or giving talks
+* Help plan PyMCon
+* Help with outreach and marketing. This could include for example reaching out to potential sponsor
+  companies, to people who could use PyMC in their work or making sure that academics who use PyMC
+  cite it correctly in their work
+* Help with our fundraising efforts
 
+### Code related contributions
 Join the discussion or submit a solution for an open issue. [See open issues](https://github.com/pymc-devs/pymc/issues)
 
-## Help improve the documentation
+
+### Documentation related contributions
 
 See all open issues in documentation [here](https://github.com/pymc-devs/pymc/issues?q=is%3Aissue+is%3Aopen+label%3A%22docs%22+)
 
 New to the open source space? Find a good beginner friendly documentation issue you can help with [here](https://github.com/pymc-devs/pymc/issues?q=is%3Aissue+is%3Aopen+label%3A%22beginner+friendly%22+label%3A%22docs%22) or [here](https://github.com/pymc-devs/pymc-examples/issues?q=is%3Aopen+label%3Adocs+label%3A%22good+first+issue%22).
 
-You will need to express your interest in the issue by commenting on it using your Github account, and you will need to use some beginner level Git to complete the Pull Request process, but don't worry! There are plenty of good [Github tutorials](https://guides.github.com/activities/hello-world/) out there, and PyMC reviewers are happy to help.
+You will need to express your interest in the issue by commenting on it using your GitHub account, and you will need to use some beginner level Git to complete the Pull Request process, but don't worry! There are plenty of good [Github tutorials](https://guides.github.com/activities/hello-world/) out there, and PyMC reviewers are happy to help.
 
 
 ## Contribute as an institution
 
-Institutions can contribute in two main ways:
+Institutions can contribute in the following ways:
 
 - By becoming [Institutional Partners](https://github.com/pymc-devs/pymc/blob/main/GOVERNANCE.md#institutional-partners-and-funding)
 - By becoming [Sponsors](https://github.com/pymc-devs/pymc/blob/main/GOVERNANCE.md#sponsors)
+- By subscribing to {ref}`Tidelift <pymc_for_enterprise>`
 
 Contact PyMC at pymc.devs@gmail.com for more information.
 
@@ -34,18 +61,37 @@ TODO: Add https://github.com/pymc-devs/pymc/blob/main/CONTRIBUTING.md
 :::{toctree}
 :hidden:
 :maxdepth: 1
-:caption: Style guides
+:caption: Tutorials
+
+pr_tutorial
+:::
+
+:::{toctree}
+:hidden:
+:maxdepth: 1
+:caption: How-to guides
+
+developer_guide_implementing_distribution
+build_docs
+running_the_test_suite
+:::
+
+:::{toctree}
+:hidden:
+:maxdepth: 1
+:caption: Reference content
 
 python_style
 jupyter_style
+pr_checklist
+release_checklist
 :::
 
 
 :::{toctree}
 :hidden:
 :maxdepth: 1
-:caption: Developer content
+:caption: In depth explanations
 
 developer_guide
-developer_guide_implementing_distribution
 :::
diff --git a/docs/source/contributing/jupyter_style.md b/docs/source/contributing/jupyter_style.md
@@ -1,4 +1,5 @@
-# PyMC Jupyter Style Guide
+(jupyter_style)=
+# Jupyter Style Guide
 
 These guidelines should be followed by all notebooks in the documentation, independently of
 the repository where the notebook is in (pymc or pymc-examples).
diff --git a/docs/source/contributing/pr_checklist.md b/docs/source/contributing/pr_checklist.md
@@ -0,0 +1,36 @@
+(pr_checklist)=
+# Pull request checklist
+
+We strongly recommended that all contribution comply with the following guidelines before being merged:
+
+*  If your pull request addresses an issue, please use the pull request title to describe the issue and mention the issue number in the pull request description. This will make sure a link back to the original issue is created.
+
+   :::{caution}
+   Adding the related issue in the PR title generates no link and is therefore
+   not useful as nobody knows issue numbers. Please mention all related
+   issues in the PR but do so only in the PR description.
+   :::
+
+*  All public methods must have informative docstrings with sample usage when appropriate.
+
+*  Please prefix the title of incomplete contributions with `[WIP]` (to indicate a work in progress). WIPs may be useful to (1) indicate you are working on something to avoid duplicated work, (2) request broad review of functionality or API, or (3) seek collaborators.
+
+*  All other tests pass when everything is rebuilt from scratch. See {ref}`running_the_test_suite`
+
+*  When adding additional functionality, consider adding also one example notebook at [pymc-examples](https://github.com/pymc-devs/pymc-examples). Open a [proposal issue](https://github.com/pymc-devs/pymc-examples/issues/new/choose) in the example repo to discuss the specific scope of the notebook.
+
+* Documentation and high-coverage tests are necessary for enhancements to be accepted.
+
+* Run any of the pre-existing examples in [pymc-examples](https://github.com/pymc-devs/pymc-examples) that contain analyses that would be affected by your changes to ensure that nothing breaks. This is a useful opportunity to not only check your work for bugs that might not be revealed by unit test, but also to show how your contribution improves PyMC for end users.
+
+You can also check for common programming errors with the following
+tools:
+
+* Code with good test **coverage** (at least 80%), check with:
+
+  ```bash
+  $ pip install pytest pytest-cov coverage
+  $ pytest --cov=pymc pymc/tests/<name of test>.py
+  ```
+
+* No `pre-commit` errors: see the {ref}`python_style` and {ref}`jupyter_style` page on how to install and run it.
diff --git a/docs/source/contributing/pr_tutorial.md b/docs/source/contributing/pr_tutorial.md
@@ -0,0 +1,68 @@
+# Pull request step-by-step
+The preferred workflow for contributing to PyMC is to fork the [GitHub repository](https://github.com/pymc-devs/pymc/), clone it to your local machine, and develop on a feature branch.
+
+## Steps
+
+1. Fork the [project repository](https://github.com/pymc-devs/pymc/) by clicking on the 'Fork' button near the top right of the main repository page. This creates a copy of the code under your GitHub user account.
+
+2. Clone your fork of the PyMC repo from your GitHub account to your local disk, and add the base repository as a remote:
+
+   ```bash
+   $ git clone git@github.com:<your GitHub handle>/pymc.git
+   $ cd pymc
+   $ git remote add upstream git@github.com:pymc-devs/pymc.git
+   ```
+
+3. Create a ``feature`` branch to hold your development changes:
+
+   ```bash
+   $ git checkout -b my-feature
+   ```
+
+
+   :::{attention}
+   Always use a ``feature`` branch. It's good practice to never routinely work on the ``main`` branch of any repository.
+   :::
+
+4. Project requirements are in ``requirements.txt``, and libraries used for development are in ``requirements-dev.txt``. The easiest (and recommended) way to set up a development environment is via [miniconda](https://docs.conda.io/en/latest/miniconda.html):
+
+   ```bash
+   $ conda env create -f conda-envs/environment-dev-py37.yml  # or py38 or py39
+   $ conda activate pymc-dev-py37
+   $ pip install -e .
+   ```
+
+   _Alternatively_ you may (probably in a [virtual environment](https://docs.python-guide.org/dev/virtualenvs/)) run:
+
+   ```bash
+   $ pip install -e .
+   $ pip install -r requirements-dev.txt
+   ```
+
+   Yet another alternative is to create a docker environment for development. See: [Developing in Docker](#Developing-in-Docker).
+
+5. 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
+   ```
+
+   to record your changes locally.
+   After committing, it is a good idea to sync with the base repository in case there have been any changes:
+   ```bash
+   $ git fetch upstream
+   $ git rebase upstream/main
+   ```
+
+   Then push the changes to your GitHub account with:
+
+   ```bash
+   $ git push -u origin my-feature
+   ```
+
+6. Go to the GitHub web page of your fork of the PyMC repo. Click the 'Pull request' button to send your changes to the project's maintainers for review. This will send an email to the committers.
+
+   :::{tip}
+   Now that your PR is ready, read the {ref}`pr_checklist` to make sure it follows best practices.
+   :::
diff --git a/docs/source/contributing/python_style.md b/docs/source/contributing/python_style.md
@@ -1,3 +1,4 @@
+(python_style)=
 # Python style guide
 
 ## Pre commit checks
diff --git a/docs/source/contributing/release_checklist.md b/docs/source/contributing/release_checklist.md
diff --git a/docs/source/contributing/running_the_test_suite.md b/docs/source/contributing/running_the_test_suite.md
diff --git a/docs/source/index.md b/docs/source/index.md
diff --git a/docs/source/learn/examples.md b/docs/source/learn/examples.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Implementing a Distribution (developer guide)`
	`1`	`+# Implementing a Distribution`
`2`	`2`
`3`	`3`	`This guide provides an overview on how to implement a distribution for version 4 of PyMC.`
`4`	`4`	`It is designed for developers who wish to add a new distribution to the library.`