Repository: sunpy/sunpy

Issue:
Improve the dev guide handling
Having given it some thought I think we can improve how we handle the different versions of the developers guide.

## Current Situation

* Upon branching for a major release we remove all docs in the dev_guide folder, apart from the stability page.
* We add a simple link on the release dev_guide index page to the latest version of the docs where the dev guide is still built.

## Desired Situation

* Stop having to remove the dev_guide source upon branching.
* Automatically redirect readers of the docs to the latest version of the dev guide.

## Changes to be made

* Modify the conf.py file so that the dev guide is excluded from builds for released versions of the docs. This could be achieved by using the [excluded_patterns](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns) configuration option. **However**, we will still need to build a `dev_tools` link in the release version of the docs so that the link shows up in the sidebar of the documentation.
* Move the stability page out of dev_docs as this should still be built for releases, it probably belongs in the code_ref section instead.
* Activate a redirect on read the docs to automatically redirect people who visit the stable URL to the latest one. (This will have to be done by a project admin one the changes have been merged and backported).

Other notes:

Only the /stable version will redirect to /latest so people who end up on specific version URLs will have to click a link to manually redirect to the latest dev_docs, i.e. mirroring the current situation.

Old versions (older than 2.0) can't be changed so they too will still manually redirect.


Discussion:
@cadair I would like to work on this task. I looked in `docs/conf.py ` file and as you mentioned some changes are needed in **excluded_patterns** it is an array consisting of 3 values `exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']`. Can you suggest what changes might be required in it? Thanks!
Hi @shubham00jain Since it is still October and Hacktoberfest is still under way, we are adopting a time limited policy and will assign this task to you to work on. Deprecated: [But if you are indeed participating Hacktoberfest please remember to start your PR title with the word `Hacktoberfest: ...`, otherwise we would not know your intentions.]

Cheers!
(Probably better to let us know in the comments not the title if you want us to put a hacktoberfest label on your PR :+1: )

@shubham00jain The `exclude_patterns` block would have to become conditional upon the version, i.e. if it's a released version (no 'dev' in the version string) then it would add the guide to the exclude list. The trickier bit is building a different index page in the case where the dev_guide is excluded, I am not sure what the best solution there is, you will have to experiment a bit.
@Cadair I have already completed the hactoberfest 2020 challenge so please don't add the tag.

I have done the following code changes:
`if is_development == False: 
    exclude_patterns.append('dev_guide')
`

Should I manually move the `stability.html` page out of dev_docs and put it inside code_ref? And do you have any suggestions on how to add the index.html file inside a new dev_guide folder. (and how to make a new dev_guide folder as well).
> Should I manually move the stability.html page out of dev_docs and put it inside code_ref?

The rst file will need moving yes, and the toctrees will need updating, in the index.rst files.

> And do you have any suggestions on how to add the index.html file inside a new dev_guide folder.

This is a little tricky, but what I think might work is to move all the current contents of the `dev_guide` folder to a subfolder like `dev_guide/content`, and conditionally ignore that subfolder in the `conf.py` file. Then in `index.rst` use jinja templating to change the contents of the `index.rst` file based on if it's a development version or not. Checkout the `stability.rst` file as an example of how this works.

You will need to get a local sphinx build going to test this out, you can use `tox -e build_docs` to build the docs locally, although you probably want to skip the gallery build for this to save you some time with `tox -e build_docs -- -D plot_gallery=0` (see the docs here: https://docs.sunpy.org/en/latest/dev_guide/documentation.html#usage ). It will probably take a little experimentation but I think it should work :smile: 
Hi @Cadair 
> This is a little tricky, but what I think might work is to move all the current contents of the dev_guide folder to a subfolder like dev_guide/content, and conditionally ignore that subfolder in the conf.py file.

I tried this approach and then built the html using `make html` inside the docs folder and I dont see any empty dev_guide folder inside `_build/html`.

I tried another approach and it works after I build it, please tell me if its doable. I have made 2 separate directories `dev_guide` and `dev_guide_release` and used a conditional in `conf.py` to include the one which is required. The `dev_guide` can contain everything which the dev version will need and the `dev_guide_release` can contain everything which the stable version needs. This way seems easier, in my opinion. :smiley:




@shubham00jain Cadair (or Stuart by name) may be away on holiday at the moment, so please wait till he gets back to answer your query. 
@kakirastern Okay thanks for telling me! Can you tell me when will he be back?
If you can open a PR with what you have working, we can look at the process and see if we can improve it.

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -123,8 +123,12 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
+
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+if not is_development:
+    exclude_patterns.append('dev_guide/contents/*')
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 source_suffix = '.rst'
@@ -226,11 +230,12 @@
 
 # -- Stability Page ------------------------------------------------------------
 
-with open('./dev_guide/sunpy_stability.yaml', 'r') as estability:
+with open('./code_ref/sunpy_stability.yaml', 'r') as estability:
     sunpy_modules = yaml.load(estability.read(), Loader=yaml.Loader)
 
 html_context = {
-    'sunpy_modules': sunpy_modules
+    'sunpy_modules': sunpy_modules,
+    'is_development': is_development,
 }
 
 
@@ -241,10 +246,11 @@ def rstjinja(app, docname, source):
     # Make sure we're outputting HTML
     if app.builder.format != 'html':
         return
-    src = source[0]
-    if "Current status" in src[:20]:
+    files_to_render = ["code_ref/stability", "dev_guide/index"]
+    if docname in files_to_render:
+        print(f"Jinja rendering {docname}")
         rendered = app.builder.templates.render_string(
-            src, app.config.html_context
+            source[0], app.config.html_context
         )
         source[0] = rendered
 


Test patch:
diff --git a/docs/dev_guide/tests.rst b/docs/dev_guide/contents/tests.rst
similarity index 100%
rename from docs/dev_guide/tests.rst
rename to docs/dev_guide/contents/tests.rst