[Docs] Move documentation sources to docs/ and include CONTRIBUTING (#7584)

Rename doc/ to docs/ so GitHub picks up docs/CONTRIBUTING.md and Doxygen keeps including it, and update all references to the old layout:

- Doxygen output now goes to docs-output/, exposed by .gitignore
- docs workflow triggers on docs/** and publishes docs-output/html
- theme submodule moved to docs/doxygen/theme
- schema URLs in both XML parsers point at docs/xsd/
- README, developer docs, desktop workflow filters, .dockerignore and gcovr config updated for the new paths

The v3 card database schema is kept as docs/xsd/cards_v3.xsd.

.dockerignore

@@ -2,6 +2,6 @@ build/
 .github/
 .tx/
 cockatrice/
-doc/
+docs/
 oracle/
 Dockerfile

.github/workflows/desktop-build.yml

@@ -15,7 +15,7 @@ on:
       - '!**.md'
       - '!.github/**'
       - '!.tx/**'
-      - '!doc/**'
+      - '!docs/**'
       - '.github/workflows/desktop-build.yml'
       - 'CMakeLists.txt'
       - 'vcpkg.json'
@@ -28,7 +28,7 @@ on:
       - '!**.md'
       - '!.github/**'
       - '!.tx/**'
-      - '!doc/**'
+      - '!docs/**'
       - '.github/workflows/desktop-build.yml'
       - 'CMakeLists.txt'
       - 'vcpkg.json'

.github/workflows/desktop-lint.yml

@@ -12,7 +12,7 @@ on:
       - '!.ci/**'
       - '!.github/**'
       - '!.tx/**'
-      - '!doc/**'
+      - '!docs/**'
       - '.ci/lint_cpp.sh'
       - '.github/workflows/desktop-lint.yml'
       - '.clang-format'

.github/workflows/documentation-build.yml

@@ -6,7 +6,7 @@ permissions:
 on:
   pull_request:
     paths:
-      - 'doc/doxygen/**'
+      - 'docs/**'
       - '.github/workflows/documentation-build.yml'
       - 'Doxyfile'
   release:
@@ -71,7 +71,7 @@ jobs:
           destination_dir: docs    # docs will be available at https://cockatrice.github.io/docs/
           external_repository: Cockatrice/cockatrice.github.io
           publish_branch: master
-          publish_dir: ./docs/html
+          publish_dir: ./docs-output/html
 
       - name: Link to Documentation Page
         if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'

.gitignore

@@ -15,4 +15,4 @@ compile_commands.json
 .cache
 .gdb_history
 cockatrice/resources/config/qtlogging.ini
-docs/
+docs-output/

.gitmodules

@@ -2,7 +2,7 @@
 	path = vcpkg
 	url = https://github.com/microsoft/vcpkg.git
 [submodule "doxygen-awesome-css"]
-	path = doc/doxygen/theme
+	path = docs/doxygen/theme
 	url = https://github.com/jothepro/doxygen-awesome-css.git
 [submodule "external/qttesting"]
 	path = external/qttesting

Doxyfile

@@ -74,7 +74,7 @@ PROJECT_ICON           = cockatrice/resources/cockatrice.png
 # entered, it will be relative to the location where Doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = docs
+OUTPUT_DIRECTORY       = docs-output
 
 # If the CREATE_SUBDIRS tag is set to YES then Doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -874,7 +874,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, Doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.
 
-LAYOUT_FILE            = doc/doxygen/DoxygenLayout.xml
+LAYOUT_FILE            = docs/doxygen/DoxygenLayout.xml
 
 # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 # the reference definitions. This must be a list of .bib files. The .bib
@@ -1091,8 +1091,8 @@ RECURSIVE              = YES
 EXCLUDE                = build/ \
                          cmake/ \
                          cmake-build-debug/ \
-                         doc/doxygen/theme/docs/ \
-                         doc/doxygen/theme/include/ \
+                         docs/doxygen/theme/docs/ \
+                         docs/doxygen/theme/include/ \
                          vcpkg/
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
@@ -1144,7 +1144,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = doc/doxygen/images
+IMAGE_PATH             = docs/doxygen/images
 
 # The INPUT_FILTER tag can be used to specify a program that Doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1183,7 +1183,7 @@ INPUT_FILTER           =
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by Doxygen.
 
-FILTER_PATTERNS        = "*.proto=python doc/doxygen/filters/proto2cpp.py"
+FILTER_PATTERNS        = "*.proto=python docs/doxygen/filters/proto2cpp.py"
 
 # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
 # INPUT_FILTER) will also be used to filter the input files that are used for
@@ -1414,7 +1414,7 @@ HTML_FILE_EXTENSION    = .html
 # of the possible markers and block names see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_HEADER            = doc/doxygen/html/header.html
+HTML_HEADER            = docs/doxygen/html/header.html
 
 # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
 # generated HTML page. If the tag is left blank Doxygen will generate a standard
@@ -1424,7 +1424,7 @@ HTML_HEADER            = doc/doxygen/html/header.html
 # that Doxygen normally uses.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_FOOTER            = doc/doxygen/html/footer.html
+HTML_FOOTER            = docs/doxygen/html/footer.html
 
 # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
 # sheet that is used by each HTML page. It can be used to fine-tune the look of
@@ -1454,9 +1454,9 @@ HTML_STYLESHEET        =
 # documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  = doc/doxygen/theme/doxygen-awesome.css \
-                         doc/doxygen/css/hide_nav_sync.css \
-                         doc/doxygen/css/cockatrice_docs_style.css
+HTML_EXTRA_STYLESHEET  = docs/doxygen/theme/doxygen-awesome.css \
+                         docs/doxygen/css/hide_nav_sync.css \
+                         docs/doxygen/css/cockatrice_docs_style.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1466,7 +1466,7 @@ HTML_EXTRA_STYLESHEET  = doc/doxygen/theme/doxygen-awesome.css \
 # files will be copied as-is; there are no commands or markers available.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_FILES       = doc/doxygen/js/graph_toggle.js
+HTML_EXTRA_FILES       = docs/doxygen/js/graph_toggle.js
 
 # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output
 # should be rendered with a dark or light theme.

README.md

@@ -84,7 +84,7 @@ Join our [Discord community](https://discord.gg/3Z9yzmA) to connect with other p
 
 ### Code
 
-To commit code to the project, please review our [Contribution Guidelines](https://github.com/Cockatrice/Cockatrice/blob/master/.github/CONTRIBUTING.md) first.<br>
+To commit code to the project, please review our [Contribution Guidelines](https://github.com/Cockatrice/Cockatrice/blob/master/docs/CONTRIBUTING.md) first.<br>
 We maintain two tags for contributors to easier find issues to potentially work on:
 - [![Good first issue](https://img.shields.io/github/issues/cockatrice/cockatrice/Good%20First%20Issue)](https://github.com/Cockatrice/Cockatrice/issues?utf8=%E2%9C%93&q=is%3Aopen%20is%3Aissue%20label%3A%22Good%20first%20issue%22%20)<br>
 Issues tagged in this way provide a simple way to get started. They don't require much experience to be worked on.
@@ -103,7 +103,7 @@ There are various places where useful information for different needs are mainta
 - [Official Wiki](https://github.com/Cockatrice/Cockatrice/wiki) `Community supported`
 - [Official Webpage](https://cockatrice.github.io/)
 - [Official README](https://github.com/Cockatrice/Cockatrice/blob/master/README.md) `This file`
-- [Official CONTRIBUTING](https://github.com/Cockatrice/Cockatrice/blob/master/.github/CONTRIBUTING.md)
+- [Official CONTRIBUTING](https://github.com/Cockatrice/Cockatrice/blob/master/docs/CONTRIBUTING.md)
 
 Cockatrice tries to use the [Google Developer Documentation Style Guide](https://developers.google.com/style/) to ensure consistent documentation.  
 We encourage everybody to improve the documentation by suggesting edits based on this guide.
@@ -163,7 +163,7 @@ The following flags (with their non-default values) can be passed to `cmake`:
 | `-DTEST=1`                 | Enable regression tests<br> **Note:** `make test` to run tests, *googletest* will be downloaded if not available                              |
 
 > [!TIP]
-> Build code documentation ([Doxygen](https://www.doxygen.nl)) according to our [configuration](https://github.com/Cockatrice/Cockatrice/blob/master/Doxyfile) into `/docs`:
+> Build code documentation ([Doxygen](https://www.doxygen.nl)) according to our [configuration](https://github.com/Cockatrice/Cockatrice/blob/master/Doxyfile) into `/docs-output`:
 > ```bash
 > doxygen Doxyfile
 > ```

docs/doxygen/README.md

@@ -1,11 +1,11 @@
 ## Building Doxygen Documentation
 
 We use [Doxygen](https://www.doxygen.nl) for our code documentation.  
-After installing the tool, you can build a HTML webpage into the `/docs` folder according to our [configuration](https://github.com/Cockatrice/Cockatrice/blob/master/Doxyfile):
+After installing the tool, you can build a HTML webpage into the `/docs-output` folder according to our [configuration](https://github.com/Cockatrice/Cockatrice/blob/master/Doxyfile):
 ```bash
 doxygen Doxyfile
 ```
-Open the `index.html` file in the `/docs/html/` folder to browse the result locally.  
+Open the `index.html` file in the `/docs-output/html/` folder to browse the result locally.  
 There is also an online version we host at the Cockatrice webpage: [cockatrice.github.io/docs](https://cockatrice.github.io/docs)
 
 Doxygen's own documenation can be found at [www.doxygen.nl/manual](https://www.doxygen.nl/manual).
@@ -25,4 +25,4 @@ FULL_SIDEBAR           = NO                       # Required for doxygen-awesome
 
 <br>
 
-Cockatrice dedicated color adjustments are configured in the [cockatrice_docs_style.css](https://github.com/Cockatrice/Cockatrice/blob/master/doc/doxygen/css/cockatrice_docs_style.css) file that uses & overrides the theme definitions.
+Cockatrice dedicated color adjustments are configured in the [cockatrice_docs_style.css](https://github.com/Cockatrice/Cockatrice/blob/master/docs/doxygen/css/cockatrice_docs_style.css) file that uses & overrides the theme definitions.

docs/doxygen/pages/developer_documentation/card_database_schema_and_parsing.md

@@ -7,8 +7,8 @@ The token file follows the schema of the card database (`tokens.xml`), too.
 
 Saved decks (`<deckname>.xml`) use a different schema.
 
-- [XSD Schema for `Card Databases`](https://github.com/Cockatrice/Cockatrice/blob/master/doc/carddatabase_v4/cards.xsd) <kbd>v4</kbd>
-- [XSD Schema for `Decks`](https://github.com/Cockatrice/Cockatrice/blob/master/doc/deck.xsd) <kbd>v1</kbd>
+- [XSD Schema for `Card Databases`](https://github.com/Cockatrice/Cockatrice/blob/master/docs/xsd/cards.xsd) <kbd>v4</kbd>
+- [XSD Schema for `Decks`](https://github.com/Cockatrice/Cockatrice/blob/master/docs/xsd/deck.xsd) <kbd>v1</kbd>
 
 
 # Card Database Parsing

gcovr.cfg

@@ -32,7 +32,7 @@ exclude = ^tests/
 
 # Vendored third-party code is not ours to cover and is never going to move the number.
 exclude = ^vcpkg/
-exclude = ^doc/doxygen/theme/
+exclude = ^docs/doxygen/theme/
 exclude = ^libcockatrice_rng/libcockatrice/rng/sfmt/
 exclude = ^libcockatrice_utility/libcockatrice/utility/peglib\.h$
 exclude = ^oracle/src/lzma/

libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_3.cpp

@@ -33,7 +33,7 @@ class ICardSetPriorityController;
 #define COCKATRICE_XML3_TAGNAME "cockatrice_carddatabase"
 #define COCKATRICE_XML3_TAGVER 3
 #define COCKATRICE_XML3_SCHEMALOCATION                                                                                 \
-    "https://raw.githubusercontent.com/Cockatrice/Cockatrice/master/doc/carddatabase_v3/cards.xsd"
+    "https://raw.githubusercontent.com/Cockatrice/Cockatrice/master/docs/xsd/cards_v3.xsd"
 
 CockatriceXml3Parser::CockatriceXml3Parser(ICardSetPriorityController *_cardSetPriorityController)
     : ICardDatabaseParser(_cardSetPriorityController)

libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_4.cpp

@@ -36,7 +36,7 @@ class ICardSetPriorityController;
 #define COCKATRICE_XML4_TAGNAME "cockatrice_carddatabase"
 #define COCKATRICE_XML4_TAGVER 4
 #define COCKATRICE_XML4_SCHEMALOCATION                                                                                 \
-    "https://raw.githubusercontent.com/Cockatrice/Cockatrice/master/doc/carddatabase_v4/cards.xsd"
+    "https://raw.githubusercontent.com/Cockatrice/Cockatrice/master/docs/xsd/cards.xsd"
 
 CockatriceXml4Parser::CockatriceXml4Parser(ICardSetPriorityController *_cardSetPriorityController)
     : ICardDatabaseParser(_cardSetPriorityController)