Doxygen: Improve file structure and includes (#6344)

doc/doxygen/extra-pages/developer_documentation/displaying_cards.md

@@ -0,0 +1,83 @@
+@page displaying_cards Displaying Cards
+
+Cockatrice offers a number of widgets for displaying cards. To pick the right one for your purpose, it is first
+important
+to determine the context in which you will be displaying the card.
+
+# In-client
+
+In the client (like in your custom widgets), you can use the existing card display widgets.
+
+## Simple Display
+
+The most general purpose of these is @ref CardInfoPictureWidget, which simply displays a picture of a card.
+
+The textual equivalent to this is @ref CardInfoTextWidget, which displays all the properties of a card in text form.
+
+## Detailed Display
+
+The convenience class @ref CardInfoDisplayWidget displays both of these widgets in a tabbed container, which allows
+choosing between either visual, textual, or both representations at the same time. It is the class that is most
+familiar to our users when a single card is highlighted or inspected, since it is used in the deck editor and in-game
+for these purposes.
+
+If you would like the user to be able to inspect a single card in your custom widget, you should
+expose a @ref CardInfoDisplayWidget to them and incorporate it as a dock widget inside your custom widget.
+
+@ref CardInfoDisplayWidget is great for ensuring that the user has all the relevant details of a card available.
+It is crucial anywhere the user might encounter a card for the first time or needs to make an informed decision.
+
+## Visual Display
+
+However, there is a reason why it is possible to have a visual-only representation of the card in the
+@ref CardInfoDisplayWidget.
+
+Cards are, by design, meant to be represented as images and cards which we can reasonably
+expect the user to know (for example, cards contained in a user made deck or explicitly chosen by the user) can be
+represented with just their image as a sort of "visual shorthand".
+
+The simplest way to do this is of course, the above-mentioned @ref CardInfoPictureWidget which simply displays the
+picture without modifications.
+
+However, there exist a couple of other convenience classes which subclass @ref CardInfoPictureWidget to accomplish some
+things which you might find useful as well.
+
+- @ref CardInfoPictureWithTextOverlayWidget displays text overlaid on top of the card picture and scales this text to
+  fit automatically.
+- @ref DeckPreviewCardPictureWidget is a @ref CardInfoPictureWithTextOverlayWidget which also features a
+  raise-on-mouse-enter animation, controlled by the global setting (TODO: specify which).
+- @ref CardInfoPictureArtCropWidget attempts to display an 'art crop' of the card by cropping the upper region of the
+  card and only displaying that.
+
+## Groups of Cards
+
+Sometimes it is useful to display images of cards in groups, for example to represent the deck in the @ref
+VisualDeckEditorWidget or during confirmation in the pre-game lobby.
+
+To this end, Cockatrice offers three convenience classes to display cards for an index in a @ref DeckListModel in a
+group and one to display all cards in a particular zone of a @ref DeckListModel.
+
+The generic way to do this is @ref CardGroupDisplayWidget, which displays cards in @ref QVBoxLayout. This class is very
+generic and it is probably a better choice to either subclass it or use one of the two existing implementations.
+
+@ref FlatCardGroupDisplayWidget displays cards using a horizontal @ref FlowWidget. This means it will fill available
+screen space, left to right with no margins, with card pictures, skipping to a new line if it overflows available screen
+space horizontally.
+
+@ref OverlappedCardGroupDisplayWidget displays cards using an @ref OverlapWidget, which displays widgets on top of each
+other in vertical columns until it exceeds available screen space in which case it will start a new column. The amount
+of overlap as well as the overlap direction is configurable.
+
+@ref DeckCardZoneDisplayWidget can be used to visualize all cards in a zone with either a @ref
+FlatCardGroupDisplayWidget or a @ref OverlappedCardGroupDisplayWidget and headed by a @ref BannerWidget. It also allows
+grouping and sorting.
+
+# In-game
+
+The in-game view is a @ref QGraphicsScene, which means any widget we want to display inside of it should be a @ref
+QGraphicsObject.
+
+- @ref CardItem
+
+
+