From 6a79c5a2cf375774d563abe26620e576b3764ebb Mon Sep 17 00:00:00 2001 From: Sequoia Ploeg Date: Wed, 20 May 2020 10:45:28 -0600 Subject: [PATCH] Update dev docs --- docs/source/dev/development_environment.rst | 16 +++++++--------- docs/source/dev/development_workflow.rst | 12 +++++------- docs/source/dev/index.rst | 18 ++++++++++-------- 3 files changed, 22 insertions(+), 24 deletions(-) diff --git a/docs/source/dev/development_environment.rst b/docs/source/dev/development_environment.rst index c2701719..61dda0c4 100644 --- a/docs/source/dev/development_environment.rst +++ b/docs/source/dev/development_environment.rst @@ -14,9 +14,8 @@ creating a :ref:`virtual environment ` to isolate the development dependencies from your system's python packages. Once that is set up, simply clone the repository into a directory of your -choosing, and after making sure your virtual environment is activated, run:: - - $ make install +choosing, and after making sure your virtual environment is activated, follow +the instructions for :ref:`building-in-place`. .. _testing-builds: @@ -39,7 +38,8 @@ repeatedly until no installations remain) and running the following commands Remember that all tests of Simphony should pass before committing your changes. -Using ``pytest`` is the recommended approach to running tests (see :ref:`running-tests`). +Using ``pytest`` (through tox) is the recommended approach to running tests +(see :ref:`running-tests`). .. _building-in-place: @@ -50,11 +50,12 @@ Building in-place For development, you can set up an in-place build so that changes made to ``.py`` files have effect without rebuild. First, run:: - $ pip install -e . + $ make install This allows you to import the in-place built Simphony *from any location the Python environment used to install it is activated*. If this is your system -Python, you will be able to use the Simphony package from any directory. +Python, you will be able to use the Simphony package from any directory, +although installing a development version in your system Python is not recommended. Now editing a Python source file in Simphony allows you to immediately test and use your changes (in ``.py`` files), without even restarting the @@ -66,9 +67,6 @@ interpreter. Using virtual environments -------------------------- -A frequently asked question is "How do I set up a development version of NumPy -in parallel to a released version that I use to do my job/research?". - One simple way to set up a development version of Simphony in parallel with a regular install is to install the released version in site-packages (perhaps using pip) and set diff --git a/docs/source/dev/development_workflow.rst b/docs/source/dev/development_workflow.rst index 0ccdbb39..41a476c2 100644 --- a/docs/source/dev/development_workflow.rst +++ b/docs/source/dev/development_workflow.rst @@ -6,12 +6,12 @@ Development workflow **Prerequisites**: You already have your own forked copy of the Simphony_ repository, you have -configured git, and have linked the upstream repository. +configured git, and have `linked the upstream repository`_. What is described below is a recommended workflow with Git. .. _Simphony: https://github.com/BYUCamachoLab/simphony - +.. _linked the upstream repository: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork Basic workflow ############## @@ -39,12 +39,10 @@ ensure that a pip installation of your updated package installs and functions properly. To test this, try installing your package locally by removing all installed versions of Simphony (by running ```pip3 uninstall simphony``` repeatedly until no installations remain) and running the following commands -(from Simphony's toplevel directory): +(from Simphony's toplevel directory): :: -``` -python3 setup.py sdist bdist_wheel -pip3 install dist/simphony-[VERSION].tar.gz -``` + $ python3 setup.py sdist bdist_wheel + $ pip3 install dist/simphony-[VERSION].tar.gz Also be sure to include tests for all the code you add, making certain the tests are thorough and always pass. diff --git a/docs/source/dev/index.rst b/docs/source/dev/index.rst index 48f8c5ba..b6073f58 100644 --- a/docs/source/dev/index.rst +++ b/docs/source/dev/index.rst @@ -2,15 +2,15 @@ Contributing to Simphony ######################## -Not a coder? Not a problem! Simphony is still a developing project, +Not a developer? Not a problem! Simphony is still a developing project, and we could use a lot of help. These are all activities we'd like to get help with (they're all important, so we list them in alphabetical order): - Code maintenance and development (architecture input welcome) -- Fundraising -- Marketing -- Writing technical documentation and examples +- Marketing, getting the word out and increasing usage +- Writing technical documentation and examples (particularly if you're just a + user but have found the project useful) Development process - summary ============================= @@ -69,8 +69,8 @@ Here's the short summary, complete TOC links are below: users can remove this step by connecting to GitHub with SSH). * Go to GitHub. The new branch will show up with a green Pull Request - button. Make sure the title and message are clear, concise, and self- - explanatory. Then click the button to submit it. + button. Make sure the title and message are clear, concise, and + self-explanatory. Then click the button to submit it. 4. Review process: @@ -146,8 +146,10 @@ Stylistic Guidelines * Set up your editor to follow `PEP 8 `_ (remove trailing white space, no tabs, etc.). Check code with - pyflakes / flake8. - .. FIXME: Do we want to use `black` instead? + flake8, and be aware that a pre-commit hook will run the autoformatter + Black_ over all of your committed code. + +.. _Black: https://black.readthedocs.io/ Test coverage