Add architecture documentation

[danielballan]

Credit to @padraic-shafer for prompting this much needed addition

[padraic-shafer]

Wow, I didn't even have to do any work and I get credit? 🤫

[padraic-shafer]

Very nice!

I think that adding subheadings will help draw the reader's eye to key topics. Also they can be linked to in other docs & discussions.

[danielballan]

Good edits. I'm stuck on getting any of the #adapter references to work; the build fails on:

Warning, treated as error:
/home/dallan/Repos/bnl/tiled/docs/source/explanations/architecture.md:40:'myst' cross-reference target not found: 'adapter' [myst.xref_missing]

[padraic-shafer]

For the links to 'H2' tags we might need to set myst_heading_anchors=2 in the sphinx build options. I haven't had to do this before, but it's referenced here.

[danielballan]

I hope we can figure out how to make explicit targets work. I agree with this advice in the docs:

In general, it is discouraged to rely on implicit targets, since they are easy to break, if for example a document/heading is moved or renamed.

[padraic-shafer]

I hope we can figure out how to make explicit targets work.

I'm trying it locally now. Will report back.

[danielballan]

Ah, I thought that the target was an arbitrary string. I did not realize that the suffix -target was significant.

[padraic-shafer]

I think the '-target' suffix is arbitrary. However, it does remove the ambiguity of potential clash with the implicitly named targets, whose style I adopted here. That might be a bad naming choice on my part, but that's the reasoning. :)

[danielballan]

Oh, you're right. Then I'm not sure what I was doing wrong in some local experiments earlier. Anyway, glad we have a working pattern now.

[dylanmcreynolds]

Would this be a good place to say (or link to) install client vs server via pip?

[padraic-shafer]

Similarly, the end of each sub-section might contain links to the relevant code documentation and further info.

E.g.

• https://blueskyproject.io/tiled/reference/python-client.html
• https://blueskyproject.io/tiled/explanations/caching.html
  • https://blueskyproject.io/tiled/reference/python-client.html#cache
• https://blueskyproject.io/tiled/how-to/tiled-authn-database.html
  • https://blueskyproject.io/tiled/reference/service-configuration.html#authentication
  • https://blueskyproject.io/tiled/tutorials/login.html
• https://blueskyproject.io/tiled/reference/service.html#adapters
• https://blueskyproject.io/tiled/reference/service.html#media-type-format-registry

[padraic-shafer]

Built locally; all ref links are working correctly.