From 6f0de48c1ef24b6ef59ab46d534d4276a2993dc6 Mon Sep 17 00:00:00 2001 From: Shane Maloney Date: Tue, 3 Nov 2020 22:37:56 +0000 Subject: [PATCH 1/2] Inital dev guide text --- docs/developers.rst | 62 +++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 63 insertions(+) create mode 100644 docs/developers.rst diff --git a/docs/developers.rst b/docs/developers.rst new file mode 100644 index 00000000..1b07dcb9 --- /dev/null +++ b/docs/developers.rst @@ -0,0 +1,62 @@ +Developers Guide +================ + +Fork and Clone Repository +------------------------- +Working of your own forked version of the repository is the preferred approach. To fork the +repository visit the repository page at (make sure you are logged +into github) and click on the fork button at the to right of the page + +Clone your forked version of the + +.. code:: bash + + git clone https://github.com//STIXCore.git + +It is also advisable to configure the upstream remote at this point + +.. code:: bash + + git remote add upstream https://github.com/i4Ds/STIXCore + + +Isolated Environment +-------------------- +It is highly recommended to work in an isolated python environment there are a number of tools +available to help mange and create isolated environment such as + +* `Anaconda `__ +* `Pyenv `__ +* Python 3.6+ inbuilt venv. + +For this documentation we will proceed using Python's venv but the step would be similar in other +tools. + +First verify the python version installed by running `python -V` or possibly `python3 -V` depending +on your system it should be greater then 3.6 + +.. code:: bash + + python3 -m venv /path/to/new/virtual/environment + +Working on code +--------------- +It's import to always be working from the most recent version of the so before working on any code +start by getting the latest changes and then creating a branch for you new code. + +.. code:: bash + + git checkout master + git pull upstream master + git checkout -b + +Branch names should ideally be short and descriptive e.g. 'feature-xmlparseing`, 'bugfix-ql-fits`, +'docs-devguide` and perferably seperated by dashes `-` rather than underscores `_`. + + +Testing +------- + + +Documentation +------------- diff --git a/docs/index.rst b/docs/index.rst index 8e3b357c..9183779f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,7 @@ This is the documentation for STIXCore. :maxdepth: 2 whatsnew/index + developers Reference/API From e06d2887043f3002e4c187263ca76274acf5e559 Mon Sep 17 00:00:00 2001 From: Shane Maloney Date: Wed, 4 Nov 2020 11:31:13 +0000 Subject: [PATCH 2/2] Update dev documentation. --- docs/developers.rst | 75 +++++++++++++++++++++++++++++++++++++++++---- setup.cfg | 2 -- 2 files changed, 69 insertions(+), 8 deletions(-) diff --git a/docs/developers.rst b/docs/developers.rst index 1b07dcb9..8ef21308 100644 --- a/docs/developers.rst +++ b/docs/developers.rst @@ -1,11 +1,18 @@ Developers Guide ================ +The instructions in this following section are based upon resources: + +* `Astropy Dev Workflow `_ +* `Astropy Dev environment `_ +* `Astropy Pull Request Example `_ +* `Sunpy Newcomers' Guide `_ + Fork and Clone Repository ------------------------- Working of your own forked version of the repository is the preferred approach. To fork the -repository visit the repository page at (make sure you are logged -into github) and click on the fork button at the to right of the page +repository visit the repository page at https://github.com/i4Ds/STIXCore (make sure you are logged +into github) and click on the fork button at the to right of the page. Clone your forked version of the @@ -32,12 +39,26 @@ available to help mange and create isolated environment such as For this documentation we will proceed using Python's venv but the step would be similar in other tools. -First verify the python version installed by running `python -V` or possibly `python3 -V` depending -on your system it should be greater then 3.6 +First verify the python version installed by running `'python -V'` or possibly `'python3 -V'` depending +on your system it should be greater then 3.6. Next create a new virtual environment in a directory +outside the git repo and activate. .. code:: bash python3 -m venv /path/to/new/virtual/environment + source /path/to/new/virtual/environment/bin/activate + #note the prompt change + +The next step is to install the required dependencies (ensure you are working from inside you virtual +environment which can be verified by comparing the path returned from `'python -m pip -V'` to the path +used in the above steps) + +.. code:: bash + + python -m pip install -e . + # to install all development dependencies documentation, testing etc use + python -m pip install -e .[dev] + Working on code --------------- @@ -50,13 +71,55 @@ start by getting the latest changes and then creating a branch for you new code. git pull upstream master git checkout -b -Branch names should ideally be short and descriptive e.g. 'feature-xmlparseing`, 'bugfix-ql-fits`, -'docs-devguide` and perferably seperated by dashes `-` rather than underscores `_`. +Branch names should ideally be short and descriptive e.g. 'feature-xmlparseing', 'bugfix-ql-fits', +'docs-devguide' and preferably separated by dashes '-' rather than underscores '_'. + +Once you are happy with your changes push the changes to github + +.. code:: bash + + git add + git commit + git push origin + +and open a pull request (PR). + +Note a series of checks will be automatically run on code once a PR is created it is recommended +that you locally test the code as outlined below. Additionally it is recommended that you install +and configure `pre-commit `_ which runs various style and code quality +checks before commit. + +.. code:: bash + + python -m pip install pre-commit + pre-commit install Testing ------- +Testing is built on the `PyTest `_ and there are a number of +ways to run the tests. During development it is often beneficial to run a subset of +test relevant to the current code this can be accomplished by running one of the commands below. + +.. code:: bash + + pytest stixcore/path/to/test_file.py:test_one # run a specific test function + pytest stixcore/path/to/test_file.py # run a specific test file + pytest stixcore/module # run all test for a modules + pytst # run all tests + + +Additionally `tox `_ is use to create and run tests in +reproducible environments. To see a list of tox environment use `'tox -l'` to run a specific +environment run `'tox -e '` or to run all simply run `'tox'`. + +.. note:: + + This is the same process that is run on the CI Documentation ------------- +Documentation is built using `Sphinx `_ similarly to the +tests above this can be run manually or through tox. To run manually cd to the docs directory and +run `'make html'` to run via tox `'tox -e build_docs'`. diff --git a/setup.cfg b/setup.cfg index c4464b49..1d5376c3 100644 --- a/setup.cfg +++ b/setup.cfg @@ -30,10 +30,8 @@ docs = sphinx sphinx-automodapi towncrier - sunpy-sphinx-theme - [options.package_data] stixcore = data/*