Use literalinclude for embeded code examples in documentation

[kitchoi]

We have code examples for documentation stored in examples/tutorials/doc_examples, but then the content tends to be copied and pasted in the source. e.g. In https://github.com/enthought/traits/blob/1af120c7d68356105d66ec6458967b5660e37e3f/docs/source/traits_user_manual/advanced.rst

Contains the same content as the code in https://github.com/enthought/traits/blob/44ca101bcfa2e5a3c31d5fab141e892fd767793d/examples/tutorials/doc_examples/examples/override_default.py

We can use literalinclude in the source to remove this duplication.

[avats-dev]

@kitchoi , I want to work on this one too.

It might take time as I have to do the cleanup for all the files in source, right?

[kitchoi]

Hi @avats-dev, that'd be really helpful, thank you! 👍

Trying to cleanup the whole source will really take a lot time. For this issue, I'd probably go over the 50 files (still quite a number) in examples/tutorials/doc_examples/examples folder to see if they are duplicated in the documentation source, and then apply literalinclude where it is safe to do so.

By "safe to do so", I was referring to the potential risk of misalignment that could occur when using literalinclude. For example, we don't want to be including the copyright header. Various parameters of literalinclude allow specifying a subregion to include, so we can skip the copyright header. But if we do so by specifying line numbers (e.g. :lines:) , this risks misalignment in the doc if the example is only changed very slightly. A better way is to create a stable marker in the example file and then use the :start-at: feature. This gets even trickier/messier if the documentation only wants to refer to a subset of the example. This is rare, as far as I see, most examples are duplicated in their entirety. But if there are exceptions (I haven't checked), some discretion is required whether literalinclude is really worth it.

Some of the examples are already referenced using literalinclude, in which case probably nothing needs to be done about those files. For example, this file: https://github.com/enthought/traits/blob/5a96cd4bfdd5aef54c637873670c5a862757df43/examples/tutorials/doc_examples/examples/observe_different_events.py is already referenced by the documentation source using literalinclude: https://github.com/enthought/traits/blob/5a96cd4bfdd5aef54c637873670c5a862757df43/docs/source/traits_user_manual/notification.rst#notification-handler

Since this issue is opened quite recently, I bet @mdickinson hasn't got a chance to veto it, just checking. :)

[avats-dev]

Thanks @kitchoi , I will start updating the docs and would ping back if I got any issues or errors.