DOC: Only show developer docs in latest by pllim · Pull Request #11342 · astropy/astropy

pllim · 2021-02-22T21:27:27Z

Description

This pull request is to hide dev docs unless it is in latest doc. For this to take effect, probably needs backport.

Stable view at #11344 .

Fixes #10443

Squash out temporary commit

Dev

https://astropy--11342.org.readthedocs.build/en/11342/install.html

Stable

From #11344

https://astropy--11344.org.readthedocs.build/en/11344/install.html

pllim · 2021-02-23T17:48:23Z

 Alternatively, if you intend to do development on other software that uses
-``astropy``, such as an affiliated package, consider installing ``astropy`` into a
-:ref:`virtualenv<using-virtualenv>`.
+``astropy``, such as an affiliated package, consider installing ``astropy`` into a `virtualenv <https://docs.astropy.org/en/latest/development/workflow/virtualenv_detail.html>`__.


Note: This gives the exact rendered look, except the link when you hover over the text.

This is fine to me for now, but it touches on another point I would like to improve in the docs, by including more details (such as how to use virtualenv) in the install docs. Having this link is maybe ok for now, since even with installation docs improvements there still might be a link like "see here for more details on virtualenv".

OTOH it might be good just to remove this link outright--as I have noted in #10508 this page is outdated and misleading.

I see that you have followed up at #11367 . Thanks!

pllim · 2021-02-23T17:49:17Z


+{%else%}
+
+The developer documentation contains instructions for how to contribute to


Dev

Stable

pllim · 2021-02-23T17:51:30Z


+{%else%}
+
+See the `latest documentation on how to test your installed version of astropy <https://docs.astropy.org/en/latest/install.html#testing-an-installed-astropy>`__.


Dev

Stable

We could also add an intersphinx target for developer docs. I'll try that out.

I see you opened issue #11366 . 👍 It would be very nice if you can get it to work. 😸

pllim · 2021-02-23T17:53:19Z


+{%else%}
+
+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>`__.


Dev

Stable

mhvk

Looks great! Some small organizational comments.

mhvk · 2021-02-23T18:19:11Z

   warnings
   utils/index
+
+{% if is_development %}


I wonder if it makes sense to just move these two items to the developer documentation section?

mhvk · 2021-02-23T18:20:13Z


+{% if is_development %}
+
 The developer documentation contains instructions for how to contribute to


How about keeping this sentence which is the same outside of the if clause? Good to keep everything as much the same as possible.

mhvk · 2021-02-23T18:21:42Z

+{%else%}
+
+The developer documentation contains instructions for how to contribute to
+Astropy or affiliated packages, as well as coding, documentation, and


Since we are removing the "install the developer version" above, how about adding here:
"...affiliated pacakges, install and test the development version, as well as ..."

DOC: Fix broken paragraph on render [ci skip]

pllim · 2021-02-24T18:24:53Z

Thanks for the review, @mhvk ! I believe I have addressed your comments. ~~Just waiting for RTD to render now.~~

taldcroft

Looks good to me, thanks @plim!

hamogu · 2021-02-25T11:51:24Z

I don't think my approval is needed (nor do I know enough about this is done to provide meaningful feedback). I merely commented on the thread at some point in time. I've removed myself form the reviewers list.

pllim · 2021-02-25T14:16:51Z

Thanks, everyone!

pllim · 2021-02-25T14:17:33Z

Hopefully this can get into the next bug fix release, so it lands in stable, @eteq or @astrofrog . 😉

embray · 2021-03-03T21:31:01Z

+            logger.warning(msg)
+
+    # Generate the page from Jinja template
+    app.connect("source-read", rstjinja)


Nice, I didn't even realize it was possible to do this.

Me neither. Thanks to @Cadair for letting me copy-paste from SunPy!

embray · 2021-03-03T21:33:08Z

+{%else%}
+
+To read the developer documentation, you will need to go to the
+`latest developer version of the documentation <https://docs.astropy.org/en/latest/#developer-documentation>`__.


I wonder if it wouldn't make sense to move the entire developer docs TOC to its own page, perhaps with a bit of expansion. If you'd like, I can make a quick prototype of what I have in mind in a separate PR, or added to this one. I am planning to do some overhaul of the developer docs anyways so it would be a good opportunity to get my feet wet.

This PR is already merged last week, so you would need to open a follow-up PR. 😉

Oh, somehow I didn't realize this was already merged. Ok then, if you think it's a good idea I can make a follow-up.

Yeah, feel free to PR. The dev docs definitely need some TLC.

DOC: Only show developer docs in latest

pllim added Docs no-changelog-entry-needed labels Feb 22, 2021

pllim added this to the v4.0.5 milestone Feb 22, 2021

pllim force-pushed the dev-docs-noshow branch from 19d788c to 39fa499 Compare February 22, 2021 22:32

pllim mentioned this pull request Feb 22, 2021

Don't include developer docs in stable branch #10443

Closed

This comment has been minimized.

Sign in to view

pllim force-pushed the dev-docs-noshow branch from a06fbe5 to 4d3a33d Compare February 23, 2021 15:09

pllim mentioned this pull request Feb 23, 2021

DOC: Only show developer docs in latest (stable view) #11344

Closed

pllim commented Feb 23, 2021

View reviewed changes

pllim marked this pull request as ready for review February 23, 2021 17:55

pllim requested review from Cadair, adrn, astrofrog, embray, eteq, hamogu, mhvk, mwcraig, saimn and taldcroft February 23, 2021 17:56

mhvk reviewed Feb 23, 2021

View reviewed changes

pllim added 2 commits February 24, 2021 13:13

DOC: Only include dev docs in dev version.

87a1485

DOC: Fix broken paragraph on render [ci skip]

DOC: Address review from mhvk [ci skip]

f747d13

pllim force-pushed the dev-docs-noshow branch from 0b937ab to f747d13 Compare February 24, 2021 18:20

taldcroft approved these changes Feb 25, 2021

View reviewed changes

Cadair approved these changes Feb 25, 2021

View reviewed changes

hamogu removed their request for review February 25, 2021 11:49

pllim merged commit c0b9754 into astropy:master Feb 25, 2021

pllim deleted the dev-docs-noshow branch February 25, 2021 14:16

embray reviewed Mar 3, 2021

View reviewed changes

embray mentioned this pull request Mar 3, 2021

Add intersphinx target for astropy-dev docs #11366

Closed

pllim mentioned this pull request Mar 5, 2021

Fix #10508 (modernize virtualenv doc) #11367

Merged

astrofrog pushed a commit that referenced this pull request Mar 16, 2021

Merge pull request #11342 from pllim/dev-docs-noshow

172b7e6

DOC: Only show developer docs in latest

eteq pushed a commit that referenced this pull request Mar 25, 2021

Merge pull request #11342 from pllim/dev-docs-noshow

7efc552

DOC: Only show developer docs in latest

pllim mentioned this pull request May 18, 2021

Documentation links broken (use latest, not stable, for dev docs) #11754

Closed


		{%else%}

		The developer documentation contains instructions for how to contribute to


		{%else%}

		See the `latest documentation on how to test your installed version of astropy <https://docs.astropy.org/en/latest/install.html#testing-an-installed-astropy>`__.


		{% if is_development %}

		The developer documentation contains instructions for how to contribute to

Uh oh!

Uh oh!

Conversation

pllim commented Feb 22, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Dev

Stable

Uh oh!

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Dev

Stable

Uh oh!

Choose a reason for hiding this comment

Dev

Stable

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim Feb 23, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Dev

Stable

Uh oh!

mhvk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim commented Feb 24, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

taldcroft left a comment

Choose a reason for hiding this comment

Uh oh!

hamogu commented Feb 25, 2021

Uh oh!

pllim commented Feb 25, 2021

Uh oh!

pllim commented Feb 25, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

pllim commented Feb 22, 2021 •

edited

Loading

pllim Feb 23, 2021 •

edited

Loading

pllim commented Feb 24, 2021 •

edited

Loading