diff --git a/docs/development/git_edit_workflow_examples.rst b/docs/development/git_edit_workflow_examples.rst index 231cbf9cd338..f64436aa0b5a 100644 --- a/docs/development/git_edit_workflow_examples.rst +++ b/docs/development/git_edit_workflow_examples.rst @@ -43,8 +43,7 @@ Set up an isolated workspace git switch -b fix-1761 upstream/main -+ Switch to your astropy development environment, assuming you are using the ``conda`` - package manager (for other options see :ref:`virtual_envs`):: ++ Switch to your astropy development environment:: conda activate astropy-dev diff --git a/docs/development/index.rst b/docs/development/index.rst index d2d16eb3b6ba..86a5ed23414d 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -12,19 +12,18 @@ guidelines. For newcomers the process may initially seem overwhelming, but with a little patience and practice you will see that it is not so complex. The key is to follow the steps outlined here and `ask for help `_ if you get stuck. -The astropy community is welcoming and friendly and will help you! +The Astropy community is welcoming and friendly and will help you! This is divided into two sections, first a quickstart guide that provides an -introduction to the development workflow, followed by a more detailed guide that covers -all aspects of contributing to Astropy and provides a reference for both developers and -maintainers. +introduction to the development workflow, followed by a number of detailed guides that +cover provide a deeper dive and a reference for both developers and maintainers. .. Important:: There are useful ways to contribute to Astropy without diving into the developer workflow which is described here. For an an overview see the `Contribute to Astropy `_ page. -Parts of this content have been adapted from the excellent +Parts of this content have been adapted from the `pandas developer documentation `_. Astropy is grateful to the pandas team for their documentation efforts. @@ -43,7 +42,7 @@ list. These issues are the most accessible ones if you are not familiar with the source code. .. toctree:: - :maxdepth: 3 + :maxdepth: 2 quickstart @@ -53,9 +52,9 @@ example with a simple bug fix. This includes more explanation of the steps and g advice for making a code change. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - workflow/git_edit_workflow_examples + git_edit_workflow_examples Details ------- @@ -64,14 +63,12 @@ Details :maxdepth: 2 development_details - virtual_pythons codeguide docguide style-guide testguide - workflow/git_resources + git_resources scripts - building ccython Maintaining astropy and affiliated packages diff --git a/docs/development/quickstart.rst b/docs/development/quickstart.rst index ea546cf16a66..e8aa10999820 100644 --- a/docs/development/quickstart.rst +++ b/docs/development/quickstart.rst @@ -58,8 +58,7 @@ https://devguide.python.org/setup/#macos. **Linux** -For Linux-based :ref:`conda ` installations, you won't have to -install any additional components. +For Linux-based installations, you won't have to install any additional components. . _contributing.forking: @@ -93,15 +92,18 @@ isolated from both your system Python and any other Python environments you may for doing other work. This is important because the development environment will often be unstable and possibly broken at times, and you don't want to break your other work. -There are *many* good options (see :ref:`virtual_envs` for discussion), but in this -quickstart guide we use the `conda `_ package +There are many good options, including a number of virtual environment managers +starting with the Python built-in `venv `_ +module. Users who have a preference for a particular virtual environment manager are +encouraged to use it! However, maintaining instructions for all of them here would be +impractical. + +For this quickstart guide we use the `conda `_ package manager provided by `miniforge `_. This is a popular choice and generally works well, especially for newcomers. It is easy to install and use on all platforms and it makes it easy to install different Python versions which can be useful for testing. -.. _contributing.conda: - Install miniforge and conda ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -110,9 +112,7 @@ If you do not already have ``conda`` installed, `download and install miniforge your system but the end result is to provide a ``conda`` executable that you can use to create and manage isolated Python environments. -Now create and activate an ``astropy-dev`` conda environment using the following: - -.. code-block:: shell +Now create and activate an ``astropy-dev`` conda environment using the following:: conda create -n astropy-dev python graphviz conda activate astropy-dev @@ -201,12 +201,6 @@ provides a quick tutorial using a test repository that may help you become more with forking a repository, cloning a fork, creating a feature branch, pushing changes and making pull requests. -Below are some useful resources for learning more about forking and pull requests on GitHub: - -* `GitHub documentation for forking a repo `_. -* `GitHub documentation for collaborating with pull requests `_. -* `GitHub documentation for working with forks `_. - Creating a feature branch ------------------------- diff --git a/docs/development/scripts.rst b/docs/development/scripts.rst index 03332752c9fe..c5eece41031a 100644 --- a/docs/development/scripts.rst +++ b/docs/development/scripts.rst @@ -1,6 +1,6 @@ -**************************** -Writing Command-Line Scripts -**************************** +******************** +Command-Line Scripts +******************** Command-line scripts in Astropy should follow a consistent scheme to promote readability and compatibility.