DOC: Fix What's New for 7.0 and bad intersphinx, remove astropy-dev tag (astropy#16646)

pllim · web-flow · commit 347cdcfce307 · 2024-07-01T16:29:40.000-04:00
* DOC: Fix What's New for 7.0

* Change the rest of astropy remote to upstream and thus finally fixing GH Issue 11383 . Also fix intersphinx and remove astropy-dev intersphinx tag.

* git_resources no longer orphaned and remove TODO note on that page not meant for users' eyes.

[ci skip]
diff --git a/astropy/coordinates/builtin_frames/icrs.py b/astropy/coordinates/builtin_frames/icrs.py
@@ -19,6 +19,6 @@ class ICRS(BaseRADecFrame):
     very close (within tens of milliarcseconds) to J2000 equatorial.
 
     For more background on the ICRS and related coordinate transformations, see
-    the references provided in the  :ref:`astropy:astropy-coordinates-seealso`
+    the references provided in the :ref:`astropy:astropy-coordinates-seealso`
     section of the documentation.
     """
diff --git a/astropy/modeling/parameters.py b/astropy/modeling/parameters.py
@@ -121,21 +121,19 @@ class Parameter:
     This class represents a model's parameter (in a somewhat broad sense). It
     serves a number of purposes:
 
-    1) A type to be recognized by models and treated specially at class
-    initialization (i.e., if it is found that there is a class definition
-    of a Parameter, the model initializer makes a copy at the instance level).
-
-    2) Managing the handling of allowable parameter values and once defined,
-    ensuring updates are consistent with the Parameter definition. This
-    includes the optional use of units and quantities as well as transforming
-    values to an internally consistent representation (e.g., from degrees to
-    radians through the use of getters and setters).
-
-    3) Holding attributes of parameters relevant to fitting, such as whether
-    the parameter may be varied in fitting, or whether there are constraints
-    that must be satisfied.
-
-
+    #. A type to be recognized by models and treated specially at class
+       initialization (i.e., if it is found that there is a class definition
+       of a Parameter, the model initializer makes a copy at the instance level).
+
+    #. Managing the handling of allowable parameter values and once defined,
+       ensuring updates are consistent with the Parameter definition. This
+       includes the optional use of units and quantities as well as transforming
+       values to an internally consistent representation (e.g., from degrees to
+       radians through the use of getters and setters).
+
+    #. Holding attributes of parameters relevant to fitting, such as whether
+       the parameter may be varied in fitting, or whether there are constraints
+       that must be satisfied.
 
     See :ref:`astropy:modeling-parameters` for more details.
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -111,7 +111,6 @@
 # add any custom intersphinx for astropy
 intersphinx_mapping.update(
     {
-        "astropy-dev": ("https://docs.astropy.org/en/latest/", None),
         "pyerfa": ("https://pyerfa.readthedocs.io/en/stable/", None),
         "pytest": ("https://docs.pytest.org/en/stable/", None),
         "ipython": ("https://ipython.readthedocs.io/en/stable/", None),
@@ -385,29 +384,22 @@ def rstjinja(app, docname, source):
         source[0] = rendered
 
 
-def resolve_astropy_and_dev_reference(app, env, node, contnode):
+def resolve_astropy_reference(app, env, node, contnode):
     """
-    Reference targets for ``astropy:`` and ``astropy-dev:`` are special cases.
+    Reference targets for ``astropy:`` are special cases.
 
     Documentation links in astropy can be set up as intersphinx links so that
     affiliate packages do not have to override the docstrings when building
     the docs.
 
-    If we are building the development docs it is a local ref targeting the
-    label ``astropy-dev:<label>``, but for stable docs it should be an
-    intersphinx resolution to the development docs.
-
-    See https://github.com/astropy/astropy/issues/11366
     """
     # should the node be processed?
     reftarget = node.get("reftarget")  # str or None
     if str(reftarget).startswith("astropy:"):
         # This allows Astropy to use intersphinx links to itself and have
         # them resolve to local links. Downstream packages will see intersphinx.
-        # TODO! deprecate this if sphinx-doc/sphinx/issues/9169 is implemented.
+        # TODO: Remove this when https://github.com/sphinx-doc/sphinx/issues/9169 is implemented upstream.
         process, replace = True, "astropy:"
-    elif dev and str(reftarget).startswith("astropy-dev:"):
-        process, replace = True, "astropy-dev:"
     else:
         process, replace = False, ""
 
@@ -591,6 +583,6 @@ def setup(app):
     # Generate the page from Jinja template
     app.connect("source-read", rstjinja)
     # Set this to higher priority than intersphinx; this way when building
-    # dev docs astropy-dev: targets will go to the local docs instead of the
+    # docs astropy: targets will go to the local docs instead of the
     # intersphinx mapping
-    app.connect("missing-reference", resolve_astropy_and_dev_reference, priority=400)
+    app.connect("missing-reference", resolve_astropy_reference, priority=400)
diff --git a/docs/development/development_details.rst b/docs/development/development_details.rst
@@ -271,12 +271,12 @@ branch from the development branch and applying your changes to your branch.
 
 First, fetch the latest development astropy and go to your branch of interest::
 
-    git fetch astropy main
+    git fetch upstream main
     git switch my-new-feature
 
 Now, do the rebase::
 
-    git rebase astropy/main
+    git rebase upstream/main
 
 You are more likely to run into *conflicts* here — places where the changes you made
 conflict with changes that someone else made — than anywhere else. Ask for help if you
@@ -329,8 +329,8 @@ the GitHub pull request page. If this is not possible, we typically squash using
 rebase --interactive <https://git-scm.com/docs/git-rebase#_interactive_mode>`_. In
 particular, you can rebase and squash within the existing branch using::
 
-  git fetch astropy
-  git rebase -i astropy/main
+  git fetch upstream main
+  git rebase -i upstream/main
 
 The last command will open an editor with all your commits, allowing you to
 squash several commits together, rename them, etc. Helpfully, the file you are
diff --git a/docs/development/docguide.rst b/docs/development/docguide.rst
@@ -53,7 +53,7 @@ the standard Astropy docstring format.
   When built in Astropy, links starting with 'astropy' resolve to the current
   build. In affiliated packages using the ``sphinx-astropy`` intersphinx mapping,
   the links resolve to the stable version of Astropy. For linking to the
-  development version, use the intersphinx target 'astropy-dev'.
+  development version, use direct URL linking.
 
 * Examples and/or tutorials are strongly encouraged for typical use-cases of a
   particular module or class.
diff --git a/docs/development/forking_button.png b/docs/development/forking_button.png
diff --git a/docs/development/git_resources.rst b/docs/development/git_resources.rst
@@ -1,18 +1,14 @@
-:orphan:
-
 .. _git-resources:
 
-***************
+*************
 Git Resources
-***************
+*************
 
 Git is central to astropy development. While Git is undeniably complex and at times
 inscrutable, in practice there is only a very small subset of commands that you will
 need to know to make contributions to Astropy. This page provides Astropy-specific
 guidance to using Git along with a list of resources for learning more about Git.
 
-**FIXME**: links in this page should be reviewed and trimmed to only the highest quality resources instead of just a grab-bag of links.
-
 If you have never used git or have limited experience with it, take a few
 minutes to look at `Git Basics`_, part of a much longer `git book`_.
 
@@ -136,7 +132,7 @@ If you want to work on some stuff with other people, where you are all
 committing into the same repository, or even the same branch, then just
 share it via GitHub.
 
-First fork Astropy into your account, as from :ref:`fork_a_copy`.
+First fork Astropy into your account, as from :ref:`contributing.forking`.
 
 Then, go to your forked repository GitHub page, e.g.,
 ``https://github.com/your-user-name/astropy``
@@ -180,7 +176,7 @@ Rebasing on main
 =================
 
 Let's say you thought of some work you'd like to do. You
-:ref:`fetch-latest` and :ref:`make-feature-branch` called
+``git fetch upstream --tags`` and :ref:`make-feature-branch` called
 ``cool-feature``. At this stage main is at some commit, let's call it E. Now
 you make some new commits on your ``cool-feature`` branch, let's call them A,
 B, C. Maybe your changes take a while, or you come back to them after a while.
diff --git a/docs/development/index.rst b/docs/development/index.rst
@@ -73,8 +73,7 @@ Details
 
 {%else%}
 
-To read the full contributor documentation, you will need to go to the :ref:`latest
-developer version of the documentation
-<astropy-dev:developer-docs>`.
+To read the developer documentation, you will need to go to the
+`latest developer version of the documentation <https://docs.astropy.org/en/latest/development/index.html>`_.
 
 {%endif%}
diff --git a/docs/development/maintainers/maintainer_workflow.rst b/docs/development/maintainers/maintainer_workflow.rst
@@ -95,7 +95,7 @@ the original pull request.
 
 But let's say the author is okay with you taking over...
 
-First, check out the ``astropy`` repository and :ref:`set_upstream_main`.
+First, :ref:`contributing.forking`.
 Now, you need to point a remote to the pull request author's fork.
 In this example, the author's username is ``octocat`` and the pull request
 branch name is ``cool-feature`` that is tied to pull request number 99999::
diff --git a/docs/development/maintainers/testhelpers.rst b/docs/development/maintainers/testhelpers.rst
@@ -73,11 +73,11 @@ Reference/API
 Astropy Test Runner
 ===================
 
-When executing tests with `astropy.test` the call to pytest is controlled
+When executing tests with ``packagename.test`` the call to pytest is controlled
 by the `astropy.tests.runner.TestRunner` class.
 
 The `~astropy.tests.runner.TestRunner` class is used to generate the
-`astropy.test` function, the test function generates a set of command line
+``packagename.test`` function, the test function generates a set of command line
 arguments to pytest. The arguments to pytest are defined in the
 `~astropy.tests.runner.TestRunner.run_tests` method, the arguments to
 ``run_tests`` and their respective logic are defined in methods of
diff --git a/docs/install.rst b/docs/install.rst
@@ -103,8 +103,8 @@ releases which are compatible with the latest ``pytest`` and ``sphinx`` releases
 Testing an Installed ``astropy``
 ================================
 
-See the :ref:`documentation on how to test your installed version of
-astropy <astropy-dev:running-tests-installed-astropy>`.
+See the `documentation on how to test your installed version of
+astropy <https://docs.astropy.org/en/latest/development/testguide.html#running-tests-installed-astropy>`_.
 
 .. _astropy-main-req:
 
@@ -236,7 +236,7 @@ Building the documentation is typically not necessary unless you are
 developing code or documentation or do not have internet access, because
 the stable, latest, and archived versions of Astropy's documentation are
 available at `docs.astropy.org <https://docs.astropy.org>`_ . The process
-is described in :ref:`astropy-dev:builddocs`.
+is described in `Building the Documentation from Source <https://docs.astropy.org/en/latest/development/docguide.html#builddocs>`_.
 
 .. _sourcebuildtest:
 
@@ -255,8 +255,8 @@ would like more control over the testing process.
 
 {%else%}
 
-See the :ref:`latest documentation on how to run the tests in a source
-checkout of astropy <astropy-dev:sourcebuildtest>`
+See the `latest documentation on how to run the tests in a source
+checkout of astropy <https://docs.astropy.org/en/latest/install.html#testing-a-source-code-build-of-astropy>`_.
 
 {%endif%}
 
@@ -281,4 +281,4 @@ pypi.anaconda.org, where the nightlies are stored, and the ``--pre`` command
 tells ``pip`` to install pre-release versions (in this case ``.dev`` releases).
 
 You can test this installation by running the tests as described in the section
-:ref:`astropy-dev:running-tests-installed-astropy`.
+`Running tests on an installed astropy <https://docs.astropy.org/en/latest/development/testguide.html#running-tests-installed-astropy>`_.
diff --git a/docs/whatsnew/7.0.rst b/docs/whatsnew/7.0.rst
@@ -12,16 +12,19 @@ the 6.1 release.
 
 In particular, this release includes:
 
-*
+* :ref:`whatsnew_7_0_quantity_to_string_formatter`
+* :ref:`whatsnew_7_0_ecsv_meta_default_dict`
+* :ref:`whatsnew_7_0_contributor_doc_improvement`
 
 In addition to these major changes, Astropy v7.0 includes a large number of
 smaller improvements and bug fixes, which are described in the :ref:`changelog`.
 By the numbers:
 
-* X issues have been closed since v6.0
-* X pull requests have been merged since v6.0
+* X issues have been closed since v6.1
+* X pull requests have been merged since v6.1
 * X distinct people have contributed code
 
+.. _whatsnew_7_0_quantity_to_string_formatter:
 
 ``Quantity.to_string`` supports ``formatter`` for formatting
 ==============================================================
@@ -48,7 +51,7 @@ Example:
     >>> q.to_string(precision=3, format='latex')
     '$123 \\; \\mathrm{m}$'
 
-
+.. _whatsnew_7_0_ecsv_meta_default_dict:
 
 Change default type for ``meta`` attribute to ``dict`` and update ECSV writer
 =============================================================================
@@ -64,6 +67,7 @@ convention conforms to the `ECSV specification
 existing ECSV readers. Previously the ``meta`` attribute could be written as an ordinary
 YAML map, which is not guaranteed to preserve the order of the keys.
 
+.. _whatsnew_7_0_contributor_doc_improvement:
 
 Improve the Contributor Documentation
 =====================================
