[Docs] Remove examples section and point through to gallery

[stichbury]

Description

Build version of PR is here

Discussed here: #629
(Internal ticket #1205

• Moved relevant useful text from the examples page to the FAQ section.
• Updated the front page to point through to the gallery, and updated the information architecture. (It would be good if the menu opened the gallery in a separate tab/window if possible -- I'm not sure how to do this with mkdocs)
• Moved your-examples.md to the explanation section
• Added @huong-li-nguyen's Charming Data video to the "Your examples" page

Screenshot

Notice

• I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":

  • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
  • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
  • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
  • I have not referenced individuals, products or companies in any commits, directly or indirectly.
  • I have not added data or restricted code in any commits, directly or indirectly.

[huong-li-nguyen]

LGTM 👍

[stichbury]

@antonymilne so this is an example of where it's flagging that I need a changelog despite only modifying docs. Presumably it's mkdocs.yml that is outside of the docs folder. Is there a way we can add this to the set of exceptions? Very minor importance, I don't have a problem with adding a changelog, but wanted to raise that there are cases where pure docs changes need them.

[huong-li-nguyen]

@antonymilne so this is an example of where it's flagging that I need a changelog despite only modifying docs.

I think it's because you change the mkdocs.yml, which is outside the docs folder. Every change inside the docs folder doesn't require a changelog file, but I agree with you - we should also ignore the mkdocs.yml if possible 🤔

[antonymilne]

Thank you for doing this! Looks good, but I have a few comments and questions that I'd like @maxschulz-COL to consider before we merge.

For the link opening in a new window vs. current one: I think this is fine how it is, since generally speaking we should prefer to open in the same tab. On the homepage we could replace the markdown link with an HTML one that includes "opens in new page" icon, but I don't think this would look good on the top bar of the navigation. So tbh I'd just leave it how you have it.

As for the changelog being needed: as you and Li said, this is because you modified mkdocs.yml that lives outside the docs. We could put this in so it's treated as part of the docs, but now that I think about it again I actually think we should change the logic so that a changelog is required for only changes to src. So docs and everything else outside src would all be excluded rather than mkdocs.yml being a special exclusion. wdyt @maxschulz-COL>? My reasoning is:

1. changelogs are really only required when there's a change to the package that affects users, which necessarily means changing code in src
2. in case there's some edge cases (e.g. dropping a Python version), you can just manually add a changelog

Overall I think this will be a slightly smoother process since a changelog would only be demanded when it might be needed.

[maxschulz-COL]

So docs and everything else outside src would all be excluded rather than mkdocs.yml being a special exclusion. wdyt @maxschulz-COL>?

I think that is fine, let's go for that

[maxschulz-COL]

Lgtm! I like it more now, highlights our examples page more, and hyou can still get to user examples quickly