diff --git a/docs/source/for_developers/contributing.rst b/docs/source/for_developers/contributing.rst index ae42361e..6c62ed55 100644 --- a/docs/source/for_developers/contributing.rst +++ b/docs/source/for_developers/contributing.rst @@ -1,5 +1,64 @@ -************ -Contributing -************ +************************* +How to Contribute to Dysh +************************* -Want to contribute to `dysh`? +tl;dr: Create an issue if you find a bug. Create a pull request if you want to contribute code + +Setting up a Dysh Development Environment +========================================= + +In order to contribute to Dysh, you will need the following: + +In order to set up a Dysh development environment, you will need the following: +#. `git `_ +#. `Python 3.9 `_ +#. `Hatch `_ +#. `Pre-commit `_ + + +See {TODO} for help on setting up these pre-requisites on your development platform +Then, you can: + +.. code-block:: bash + + git clone https://github.com/GreenBankObservatory/dysh.git + cd dysh + pre-commit install # Install the pre-commit hooks into your git repo + hatch shell # Create virtual env, install dependencies, and activate the environment + + +Contributing Code +================= + +All code contributions will require: +#. `A GitHub account `_ +#. `A fork the Dysh repo `_ +#. An issue to be created + + +Two example workflows: + +Feature Request/Bug Report +++++++++++++++++++++++++++ + +1. Check the `Dysh Issues `_ to see if the bug/feature has already been reported/requested +2. If not, `create an Issue `_ +3. Dysh developers will communicate with you via the Issue to help diagnose the bug + +Bugs will be fixed as developer time allows. + +I want to add a feature/fix a bug ++++++++++++++++++++++++++++++++++ + +I want to fix a bug +If you think you know how to fix the bug, we would welcome a bug fix! + +1. In (a clone of) your fork, create a "feature branch" with a descriptive name like ``desc-of-your-bug`` +2. Commit code to fix the bug +3. Create a `pull request `_ +4. Wait for Dysh developers to communicate with you further! + + +6. Check the `Dysh Issues `_ to see if a similar feature has already been requested +7. If not, `create an Issue `_ describing the feature +8. Dysh developers will communicate with you via the Issue to help diagnose the bug diff --git a/docs/source/for_developers/doc_standards.rst b/docs/source/for_developers/doc_standards.rst index 05827250..ca047400 100644 --- a/docs/source/for_developers/doc_standards.rst +++ b/docs/source/for_developers/doc_standards.rst @@ -2,40 +2,41 @@ Documentation ************* -Setting Up Sphinx Autobuilds -============================ +How does it work, and how can you contribute to it? -Here are the steps to set up Sphinx autobuilds so that you can check your documentation edits live. +How to Contribute to Dysh Docs +============================== -1. First, navigate to your `dysh` root directory and activate the `hatch` environment. +Local Builds +++++++++++++ -.. code-block:: bash +The first thing you'll want to do is get the docs building locally. This makes it very easy to develop, and you can be *nearly certain* that the docs will build on Read the Docs if they have successfully built locally (assuming you've rememembered to commit all your files...) - $ hatch shell +To run a live docs server (i.e. reload on changes) -2. Next, tell hatch to run the docs. The docs will be published at `http://127.0.0.1:8000/`. +.. code-block:: sh -.. code-block:: bash + cd "$DYSH_REPO_ROOT" + hatch run docs - (dysh) $ hatch run docs +You can pass any arguments through to ``sphinx-autobuild``, e.g. to bind to a specific host and port: -3. If you would like the docs to publish at a specific host and port, such as `http://thales:9876`, then add the appropriate flags: +.. code-block:: sh -.. code-block:: bash - - (dysh) $ hatch run docs --host thales --port 9876 - -4. You may now make changes in the `dysh/docs/` directory and see the live changes at the appropriate URL in your browser. To close the server, simply `CTRL+C`. + cd "$DYSH_REPO_ROOT" + hatch run docs --host 0.0.0.0 --port 8001 Docstring Format ================ All Python functions must contain a docstring which follows the NumPy convention. You can learn more about this convention here: https://numpydoc.readthedocs.io/en/latest/format.html -Mermaid Diagrams -================ +Flowcharts/Diagrams ++++++++++++++++++++ + +Where possible, please prefer Mermaid to pre-rendered flowcharts/diagrams. It makes it easy to embed the full source in the docs, which makes future edits significantly easier. -Diagrams can be directly in these text files by using the `sphinxcontrib-mermaid` package. Here's an example: +Dysh supports Mermaid Diagrams via the ``sphinxcontrib-mermaid`` package. Here's an example: .. mermaid:: @@ -43,4 +44,15 @@ Diagrams can be directly in these text files by using the `sphinxcontrib-mermaid A[Item 1] --> B[Item 2] B --> C[Item 3] -To learn more, see the `package documentation `_. Mermaid also offers an `online editor `_ which can be used to design diagrams. +To learn more, see the `sphinxcontrib-mermaid documentation `_. Mermaid also offers an `online editor `_ which can be used to design diagrams. + +Read the Docs +============= + +Dysh's documentation is hosted on Read the Docs, at https://readthedocs.org/projects/dysh/. Docs are built directly from the Dysh GitHub repo. + +RTD hosts several different active versions of Dysh documentation: + +- ``latest``: built from the latest commit on ``main`` +- ``stable``: built from that latest stable version tag +- ``release-X.Y``/``vX.Y``: built from the latest commit on a given release branch diff --git a/docs/source/for_developers/git_workflows.rst b/docs/source/for_developers/git_workflows.rst index 868525f5..e4634a09 100644 --- a/docs/source/for_developers/git_workflows.rst +++ b/docs/source/for_developers/git_workflows.rst @@ -1,84 +1,153 @@ -************* -Git Workflows -************* +************ +Git Workflow +************ -Branches -======== +Background +========== -The development team employs a GitFlow workflow with personal branching. This means that code in the `main` branch should always be in a releasable state. Developers should maintain their own development branches and commit changes to a `release-x.y.z` branch. When it's time to release, a dedicated team member will merge the `release-x.y.z` branch with the `main` branch and tag it accordingly. +Dysh uses the `OpenAstronomy model for its branching and release structure `_. In practice, this essentially means that we are using a standard "feature branch" workflow, where new features are added via Pull Requests based on ``main``. + +If you are an external collaborator, you will need to create Pull Requests from a fork of Dysh, but the instructions below should otherwise be fairly similar. + +Developers are welcome to manage their git workflow however they want, but using the `GitHub CLI `_ or `GitHub Desktop `_ simplify many operations. + +How to Contribute +================= + + +There are two types of workflow: +1. Contributing to a future release. This is the most common workflow +2. Patching a previous release. This involves changes to a "release branch" -- changes will *not* go on `main` + +Below is a diagram demonstrating both of these workflows. They are explored in more depth farther down. .. mermaid:: - %%{init: { 'theme': 'base' } }%% + %%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchOrder': 10}} }%% gitGraph - commit id: "1" - commit id: "2" - branch release-x.y.z order: 1 - commit id: "3" - branch personB-devel order: 3 - branch personA-devel order: 2 - commit id: "4" - checkout personB-devel - commit id: "5" - commit id: "6" - checkout personA-devel - commit id: "7" - commit id: "8" - checkout release-x.y.z - merge personA-devel id: "9" - commit id: "10" - checkout personB-devel - merge release-x.y.z id: "11" - commit id: "12" - commit id: "13" - checkout release-x.y.z - merge personB-devel id: "14" + + commit id: "freeze 0.2" tag: "v0.3dev" + branch v0.2 order: 11 + + checkout v0.2 + commit id: "start v0.2 beta test" tag: "v0.2.0b1" + + branch v0.2.0b1_fix order: 14 + commit id: "fix bugs from beta" + checkout v0.2 + merge v0.2.0b1_fix id: "Release v0.2.0rc1" tag: "v0.2.0rc1" + commit id: "Release v0.2.0" tag: "v0.2.0" + commit id: "Bug fix for v0.2" tag: "v0.2.1" + checkout v0.2 + + checkout main + branch feature_x order:3 + commit id: "start feature x" + commit id: "finish feature x" checkout main - merge release-x.y.z id: "15" tag: "release-x.y.z" + merge feature_x id: "freeze 0.3" tag: "v0.4dev" -Releases -======== + branch v0.3 order:100 + commit id: "start v0.3 beta test" tag: "v0.3.0b1" + checkout main -Release branches will be locked once work on the next release begins. + branch feature_y order:1 + checkout feature_y + commit id:"implement feature y" + checkout main -Setting up your own development branch -====================================== +Contribute to ``main`` (Add to a Future Release) +++++++++++++++++++++++++++++++++++++++++++++++++ -In the directory you want to work in, set up the repo: -`$ git clone git@github.com:GreenBankObservatory/dysh.git` +Primary development is always done on a feature branch off of `main`. The only way for code to get into `main` is via a `Pull Request `_ on the `Dysh GitHub `_. A Pull Request is essentially a group of commits with a common purpose, and it is associated with a discussion thread. It encapsulates both the code changes themselves, and the explanation of why they are being made, how they work, etc. -`$ cd dysh` +Here is the lifecycle of a simple Pull Request: -`$ git checkout [branch-name]` +.. code-block:: sh -with the [branch-name] replaced by the current release or other branch. Currently, this is "release-0.2.0". Then setup your own development branch with your first name followed by "-devel": + git checkout main + git fetch origin main + git checkout -b my-cool-new-feature + # + git commit -am "Desc of changes" + # + git commit -am "More changes" + git push origin my-cool-new-feature -`$ git checkout [name-devel]` +At this point, the developer considers the work complete, and the Dysh GitHub has a new branch, ``my-cool-new-feature``, and the developer's repo will look like: -Now make and activate a python virtual environment so your work doesn't impede or break other concurrent projects. Whenever you do some work, make sure you are in your own development branch. When you are ready to merge changes made by other developers into your own branch, +.. mermaid:: -`$ git checkout release-0.2.0` + %%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true}} }%% -`$ git pull` + gitGraph + commit id:" " + branch my-cool-new-feature + checkout my-cool-new-feature + commit id: "Desc of changes" + commit id: "More changes" -`$ git checkout [name-devel]` +Now they can open a Pull Request in the Dysh repo on GitHub. -`$ git merge release-0.2.0` +At this point, a few things happen: -When you are ready to commit changes, review what's been changed with +1. GitHub CI kicks off, which runs code quality checks and unit tests +2. Another developer will review your code contribution +3. Discussion of the new feature will occur +4. Eventually, the PR will be accepted or rejected + - If it is accepted, it will be merged into ``main`` and be a part of the next release + - If it is rejected, it will go nowhere -`$ git status` -and then add the intended files using +If accepted, the Dysh repo will now look like: -`$ git add [path/to/changed/file]` +.. mermaid:: -check `dysh/.gitignore` to make sure you are not adding ignored files (virtual environment data, `_build/`, etc.). Then commit and push with + %%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true}} }%% -`$ git commit -m "[this is my commit message]"` + gitGraph + commit id:" " + branch my-cool-new-feature + checkout my-cool-new-feature + commit id: "Desc of changes" + commit id: "More changes" + checkout main + merge my-cool-new-feature -`$ git push` -The first time you run this, it will give a command about setting the origin upstream. Simply copy and run that command. Users of GitHub Desktop can also achieve all of these above steps using the app interface. Next, go to the `dysh GitHub page `_ and submit a pull request. + + +Contribute to a Previous Release (Add to a release branch) +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In this example, release ``v0.2.0`` has been released, and development has started on ``v0.3.0`` (on ``main``). Then, a bug is reported in ``v0.2.0``, necessitating a bug fix. + + +.. mermaid:: + + %%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': true, 'showCommitLabel':true}} }%% + + gitGraph + + commit id: "freeze 0.2" tag: "v0.3dev" + branch v0.2 + + checkout v0.2 + + checkout main + commit id: " " + checkout v0.2 + + commit id: "Release 0.2.0" tag: "v0.2.0" + branch v0.2.0-bug-fix + commit id: "fix bug" + checkout v0.2 + merge v0.2.0-bug-fix id: "Release v0.2.1" + commit id: "Release 0.2.1" tag: "v0.2.1" + + checkout v0.2 + + checkout main + commit id: " " diff --git a/docs/source/for_developers/index.rst b/docs/source/for_developers/index.rst index 2691dc35..03c50db3 100644 --- a/docs/source/for_developers/index.rst +++ b/docs/source/for_developers/index.rst @@ -2,15 +2,16 @@ For Developers ************** -Here's some info that developers might find useful +Documentation specifically for people who want to contribute code to Dysh .. toctree:: :maxdepth: 2 + setup_dev_env contributing - install + git_workflows doc_standards + + install github_integrations - git_workflows black - terminal_messages diff --git a/docs/source/for_developers/setup_dev_env.rst b/docs/source/for_developers/setup_dev_env.rst new file mode 100644 index 00000000..96ead75b --- /dev/null +++ b/docs/source/for_developers/setup_dev_env.rst @@ -0,0 +1,78 @@ +************************************ +Setting Up a Development Environment +************************************ + + +Pre-Requisites +============== + +There are a few core things you will need to develop Dysh: + +1. A Linux computer (Mac and Windows should also work, but we don't have docs for those) +2. Python (specifically you should be using the minimum-supported version of Python; see ``pyproject.toml``) +3. `pre-commit `_: used to enforce code quality checks +4. `Hatch `_ (optional, technically) + +Python +------ + +See site-specific instructions [TODO] for GBO, UMD, etc. instructions -- the necessary version of Python is probably already available somewhere. + + +If you do not already have access to the minimum-supported version of Python, you will need to install it. This can be done manually via `the official site `_, but it is much easier to use pyenv. + + +Once you can run ``python --version`` and see the correct version pop up, you are ready to move on. + +pre-commit +---------- + + + +Dysh Development Environment +============================ + +Start to finish, how do you initialize a Dysh development environment? + + +Via Hatch +--------- + +.. code-block:: sh + + git clone git@github.com:GreenBankObservatory/dysh.git + cd dysh + hatch shell # + hatch run test # Prove that the tests can run and pass + +Manual Virtual Environment +-------------------------- + +In some environments it makes more sense to manage your environments yourself. For example, at GBO we have a variety of hosts that all mount a common filesystem, but can have different OS versions. Here the standard "one env per project per user" breaks down, and it is better to manage things yourself. + +.. code-block:: sh + + git clone git@github.com:GreenBankObservatory/dysh.git + cd dysh + python3.9 -m venv /path/to/venv # Create your venv + source /path/to/venv/bin/activate # Activate your venv + pip install -e .[all] # Install dysh in edit mode, including all extra deps + hatch run test # Use hatch to trigger pytest inside your manually-created venv + + +Advanced Cases +============== + +If you need to exactly replicate the Python dependencies of either: +1. A given CI deployment +2. A given Dysh deployment at GBO (or elsewhere) + +You will instead be relying on the lockfile (``requirements.txt``) to provide exact version pins of all of your dependencies. + +With the same version of Python as the environment you are trying to replicate, and with the same OS (or as similar as possible): + +.. code-block:: sh + + python3.9 -m venv /path/to/venv # Create your venv + source /path/to/venv/bin/activate # Activate your venv + pip install -r requirements.txt # Install from lockfile diff --git a/docs/source/for_developers/terminal_messages.rst b/docs/source/for_developers/terminal_messages.rst deleted file mode 100644 index 4c4c8d6b..00000000 --- a/docs/source/for_developers/terminal_messages.rst +++ /dev/null @@ -1,30 +0,0 @@ -***************** -Terminal Messages -***************** - -Dysh Rich Console -================= - -The `dysh/config/rich_theme.py` file defines a `rich.console.Console` object called `DyshRichConsole`, which employs a `rich.highlighter.RegexHighlighter` object called `DyshRichHighlighter` to highlight syntax. - -To use the `DyshRichConsole` to print pretty messages, import the following at the top of your code: - -.. code:: - - from dysh.config.rich_theme import DyshRichConsole - -Then, to use it: - -.. code:: - - DyshRichConsole.print(foo) - -Friendly Messages -================= - -`dysh/util/messages.py` has a class called `FriendlyMessages`, which includes general messages like greetings. - -System Messages -=============== - -`dysh/util/messages.py` has another class called `SystemMessages`, which give information about the system. diff --git a/docs/source/index.rst b/docs/source/index.rst index 1973b30f..b753dcb5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -17,11 +17,11 @@ Contents background/index getting_started/index examples/index - modules/index for_beta_testers/index for_developers/index performance_testing/index design/index + modules/index Indices and tables ================== @@ -44,9 +44,10 @@ Credits Dev Team -------- -| Marc Pound (UMD) -| Victoria Catlett (GBO) -| Peter Teuben (UMD) -| Pedro Salas (GBO) -| Evan Smith (GBO) -| Thomas Chamberlain (GBO) + +- Marc Pound (UMD) +- Victoria Catlett (GBO) +- Peter Teuben (UMD) +- Pedro Salas (GBO) +- Evan Smith (GBO) +- Thomas Chamberlin (GBO) diff --git a/docs/source/modules/index.rst b/docs/source/modules/index.rst index f2ea3fc3..3d78b920 100644 --- a/docs/source/modules/index.rst +++ b/docs/source/modules/index.rst @@ -1,6 +1,8 @@ -**************** -Modules and APIs -**************** +***************** +API Documentation +***************** + +Documentation for Dysh's public API .. toctree:: :maxdepth: 2