Doc: Restore API documentation URLs (#1386)

* Generate files into the api folder so that URLs stay the same

But in order to keep index.rst to be maintained manually,
the ci command no longer reset the folder. Developers
should do git clean before regenerating docs to ensure
clean initial state.

(cherry picked from commit a7ef805)

.gitignore

@@ -16,4 +16,6 @@ docs/build/
 traitsui/_version.py
 
 # Ignore automatically generated API documentation source
-docs/source/api/autogenerated/
+# ... except index.rst which is manually maintained.
+docs/source/api/*.rst
+!docs/source/api/index.rst

docs/source/api/index.rst

@@ -10,4 +10,4 @@ TraitsUI.  For user documentation, please read the
 .. toctree::
     :maxdepth: 3
 
-    autogenerated/traitsui
+    traitsui

etstool.py

@@ -397,10 +397,9 @@ def docs(runtime, toolkit, environment):
     click.echo(
         "Regenerating API docs in  '{environment}'".format(**parameters)
     )
-    output_path = os.path.join("docs", "source", "api", "autogenerated")
-    if os.path.exists(output_path):
-        rmtree(output_path)
-    os.makedirs(output_path)
+    output_path = os.path.join("docs", "source", "api")
+    if not os.path.exists(output_path):
+        os.makedirs(output_path)
     commands = [
         "edm run -e {environment} -- sphinx-apidoc "
         "-e "