"cdk docs" opens on "index" and it's not very useful

[eladb]

cdk docs should open on "welcome.html" instead of "index.html"

Also, it would be nice to be able to do "cdk docs getting-started" and it will open on "getting-started.html".

[eladb]

@Doug-AWS, @RomainMuller and I are thinking that perhaps the right solution to this is to simply rename welcome.rst to index.rst (and either delete index.rst altogether or rename it to toc.rst or something like that if we still think it's useful. Thoughts?

[Doug-AWS]

Hmm. Every AWS SDK (and every Sphinx project I've seen) uses this structure. I'll investigate.

[Doug-AWS]

The real issue is that index.html contains an exploded table of contents, where every single topic page is listed. It wouldn't be so bad if it had just the 10 entries I have in index.rst:

.. toctree::
Welcome
Getting Started
Developing Apps
Developing Libraries
Examples
Concepts
Tools
Advanced Topics
Glossary
Reference

[eladb]

I agree that this is /also/ an issue, but the experience we want is that when people open the root directory of the docs in their browser (open ~/.cdk/docs), they will see the welcome page and not this index.

What happens if we rename index.rst to toc.rst and welcome.rst to index.rst?

[eladb]

@Doug-AWS if it makes more sense from your end to leave index as is, we can simply route cdk docs to open welcome by default. If you are good either way, I rather we change index to be the page we want users to see first, which is a web standard.

[Doug-AWS]

Not sure. The brazil build produces this experience. The index.html that brazil produces re-routes as you suggest in the HEAD section:

  <script type="text/javascript">
     <!--
    var myDefaultPage = "welcome.html";
       	var myPage = document.location.search.substr(1);
       	var myHash = document.location.hash;
    
          if (myPage == null || myPage.length == 0) {
             myPage = myDefaultPage;
          } else {
             var docfile = myPage.match(/[^=\;\/?:\s]+\.html/);
             if (docfile == null) {
   				myPage = myDefaultPage;
	     		 } else {
                myPage = docfile + myHash;
             }
          }
          self.location.replace(myPage);
--></script>