Add intro tutorial which pulls content from interactive examples

[corranwebster]

This extracts and links to the introduction to traits tutorial in traits/examples and makes it available via the documentation.

Done this way rather than copying so we have one source for the actual content.

No new, code, just documentation.

Checklist

• Tests
• Update API reference (docs/source/traits_api_reference)
• Update User manual (docs/source/traits_user_manual)
• Update type annotation hints in traits-stubs

[mdickinson]

A few typos noted in passing; I haven't tested the changes in either the built documentation or the demo app.

[mdickinson]

Closing and re-opening to retrigger CI build

[kitchoi]

I have tested this with the demo application. Looks fine in general but the code snippet looks slightly odd but I think it is an existing issue, hence orthogonal:

I have also tested the HTML sphinx documentation locally. Links are working and the rendering looks fine there.

However I find the "Tutorials" link is mentioned too early in the main page compared to the high-level introduction (see another comment):

[kitchoi]

This being at the top makes it more likely the first thing a developer would read. But I think the Introduction section is more suitable as the first thing to read because it provides a higher-level summary of the capabilities of Traits: https://docs.enthought.com/traits/traits_user_manual/intro.html#introduction

I'd think this tutorial needs to be read after the introduction because it assumes one knows what Traits is for, is interested in it, and wanted to start learning to use it.

Once we establish a structure of our documentation to contain gentle guides/tutorials/API references/example snippets, it will likely get replicated to other ETS repository. So it might be worth thinking about this earlier.

(I personally like sqlalchemy's documentation (e.g. Version 1.3). Its landing page guides you through an overview, installation, and then provide links to tutorial and API references.)

[mdickinson]

I merged master in to fix (I hope) the unrelated CI failures.

[corranwebster]

I have tested this with the demo application. Looks fine in general but the code snippet looks slightly odd but I think it is an existing issue, hence orthogonal:

That looks like it's not picking up the CSS for the HTML view?

[mdickinson]

I'd like to get this in for the impending Traits 6.2 release. There are some important discussions going on, and I don't want to shut those down. But on the basis that

• The docs with the tutorial are a (huge) net improvement over the docs without the tutorial, and
• We can continue to refine the documentation after the release

I'd like to merge this. @kitchoi, @corranwebster are there any points that you think it's really important to address before this is merged?

[kitchoi]

Agreed that a doc with tutorial is a net improvement. But the order in the index feels odd enough to me that I'd propose somehow making tutorial follow the "Introduction". I will have a look in how the TOC can be changed to make that happen.

[kitchoi]

See #1394

[kitchoi]

@mdickinson Please do go ahead to close/merge #1394 and this one as you see fit. When I opened #1394, I really did not think it would be objected to because the ordering was apparently odd to me - it was not my intention to slow down progress.

[mdickinson]

I took the liberty of fixing a hyphenation nitpick; will merge when CI signs off.

I'll open a new issue for refactoring of the landing page.

[mdickinson]

I'll open a new issue for refactoring of the landing page

Opened #1413.