Merge pull request #49 from heartfin/48-doxygen

docs: Add Doxygen and project-related documentation

.github/workflows/doxygen.yaml

@@ -0,0 +1,40 @@
+name: doxygen
+run-name: Generate and deploy Doxygen documentation
+on: 
+  push:
+    branches:
+      - "master"
+  workflow_dispatch: {}
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        uses: actions/configure-pages@v3
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+          cache: 'pip' # caching pip dependencies
+      - run: pip install doxyqml
+      - name: Doxygen
+        uses: uses: mattnotmitt/doxygen-action@v1.9.5
+      - name: Upload GitHub pages artifact
+        uses: "actions/upload-pages-artifact@v2"
+        with:
+          path: "doxygen/html/"
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: "actions/deploy-pages@v2"

.gitignore

@@ -5,6 +5,7 @@ rpm/*.spec
 build/
 build-*/
 .dub/
+doxygen/
 
 # IDE files
 *.user

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "core/doc/doxygen-awesome-css"]
+	path = core/doc/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git
+[submodule "3rdparty/doxygen-awesome-css"]
+	path = 3rdparty/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

3rdparty/doxygen-awesome-css

@@ -0,0 +1 @@
+Subproject commit 5b27b3a747ca1e559fa54149762cca0bad6036fb

README.md

@@ -2,8 +2,50 @@
 [!["Chat via Matrix"](https://img.shields.io/matrix/sailfin:netsoj.nl?label=Chat%20via%20Matrix&logo=matrix&server_fqdn=meetriks.netsoj.nl&style=for-the-badge)](https://matrix.to/#/#sailfin:netsoj.nl)  
 Sailfin is a [Sailfish OS](https://sailfishos.org) client for [Jellyfin](https://jellyfin.org), a media server, written in C++ and qml.
 
+## Download
+This application can be found on [OpenRepos.net](https://openrepos.net/content/ahappyhuman/sailfin)
+
 ## Screenshots (running on Sailfish OS)
-<img alt="Screenshot showing the library root" src="graphics/screenshot-sailfish-1.png" width="33%" /> <img alt="Screenshot showing TV show page" src="graphics/screenshot-sailfish-2.png" width="33%" /> <img alt="Screenshot showing the video player" src="graphics/screenshot-sailfish-3.png" width="33%" />
+<img alt="Screenshot showing the library root" src="graphics/screenshot-sailfish-1.png" width="33%" /> <img alt="Screenshot showing TV show page" src="graphics/screenshot-sailfish-2.png" width="33%" />
+
+## Contributing
+Please [see this page for contribution guidelines](https://sailfin.github.io/harbour-sailfin/contributing.html).
+and [this page for how the Jellyfin-Qt library works](https://sailfin.github.io/harbour-sailfin/contributing.html).
+
+## Code layout
+```
+├── 3rdparty               3rd-party libraries
+├── cmake                  Additional CMake modules
+│
+├── core                   The core Qt library named Jellyfin-Qt
+│   ├── codegen            Template files for code generation based on the OpenAPI spec
+│   ├── dbus               DBus interface description files
+│   ├── doc                Extra documentation files for the generated documentation
+│   ├── include            Publically includable files
+│   ├── qrc                Resources for the library
+│   └── src                C++ source code
+│
+├── graphics               Source graphics files, meant to be edited
+│   └── qtquick-theme      Custom graphics for the QtQuick theme 
+│
+├── qtquick                QtQuick application for testing, based on the core library
+│   ├── assets             Custom assets
+│   ├── qml                QML UI files
+│   ├── SailfinStyle       QtQuick theme files
+│   └── src                C++ code
+│
+├── rpm                    Files for packaging the application
+│
+└── sailfish               The Sailfish OS app based on the core library
+    ├── icons              Launcher icons
+    ├── qml                QML UI files
+    │   ├── components     Reusable QML components
+    │   ├── cover          Cover pages
+    │   ├── licenses       Licence texts for libraries
+    │   └── pages          Application pages
+    ├── src                C++ source code
+    └── translations       UI translation files
+```
 
 ## License
 This application is licensed under the LGPLv2.1 license, although you may opt to choose a newer version of the LGPL if you want so.

core/doc/contributing.md

@@ -0,0 +1,77 @@
+\page contributing Contributing
+\brief All resources for (potential) contributors
+
+This page should contain all resources for people who'd like to contribute to the project. 
+If that happens to be you, thank you for considering to contribute to this project! 
+This page will describe how the process goes, what code style this project uses and more useful information.
+
+# Development process
+Development happens at [GitHub](https://github.com/heartfin/harbour-sailfin). 
+Currently, both the library Jellyfin-Qt and the [Sailfish OS](https://sailfishos.org) app named Sailfin are developed in the same repository.
+
+## Create or find an issue to work on
+If you want to contribute code, please check if an issue exists. 
+Otherwise, create an issue describing what feature you'd like to develop before creating a merge request.
+
+## Start working on your code
+Clone the git repo and create a new branch. 
+If you have commit access to the repository, please create a branch in the form of `<issue-number>-<issue-title>`. 
+For example, `36-control-remote-jellyfin-sessions`.
+
+Now you can start writing your code and create commits. 
+Please create focussed commits, that is, do not commit anything not related to the issue you are working on.
+Also state what you're changing in the commit message and add an entry in the file `rpm/harbour-sailfin.changes`.
+
+If this is your first time contributing to the project, don't be shy and feel free to add your name to the contributors list in `sailfish/qml/pages/AboutPage.qml`!
+
+## Submit a merge request
+Now that you have finalised your commit, you can create a merge request on the repository.
+Make sure that you have followed the contribution guidelines on this page.
+Someone will review it and if all is good, they will merge it in.
+
+Congratulations on your contribution!
+
+# Code style guidelines
+The code should follow the [Sailfish OS Code Conventions](https://docs.sailfishos.org/Develop/Apps/Coding_Conventions/) with the following exceptions:
+
+## Exceptions for C++
+- Put curly braces on the same line as the declaration, example:
+  ```cpp
+  int foo() {
+      // implementation
+  }
+  ```
+  instead of
+  ```cpp
+  int foo()
+  {
+     // implementation
+  }
+  ```
+  Rationale: I hate pressing enter and am used to the former. Moreover, it is already all over the place. Bad rationale, I know.
+
+- Close namespace brackets with a comment in the form `// NS Jellyfin`, example:
+  ```cpp
+  namespace Jellyfin {
+  namespace Nested {
+      // Content
+  } // NS Nested
+  } // NS Jellyfin
+  ```
+  Rationale: Easy to know what namespace the bracket closes, since namespaces tend to span over large portions of a file.
+
+- Use include guards in the form of `NAMESPACE_CLASSNAME_H`. Example:
+  ```cpp
+  #ifndef JELLYFIN_MODEL_USER_H
+  #define JELLYFIN_MODEL_USER_H
+  namespace Jellyfin {
+  namespace Model {
+
+  class User {
+      // Methods etc
+  };
+
+  } // NS Model
+  } // NS Jellyfin
+  ```
+

core/doc/custom.css

@@ -0,0 +1,15 @@
+html {
+		--primary-color: #be48d6;
+		--primary-dark-color: #7a2e89;
+		--primary-light-color #e256ff;
+}
+
+@media (prefers-color-scheme: dark) {
+    html:not(.light-mode) {
+		--primary-color: #be48d6;
+		--primary-dark-color: #7a2e89;
+		--primary-light-color #e256ff;
+    }
+}
+
+

core/doc/guide/apimodel-loader.md

@@ -0,0 +1,5 @@
+\page guide-apimodel-loader ApiModel and Loaders
+\brief This will give an overview of how the ApiModel and Loaders interact.
+
+\todo
+This guide should still be written

core/doc/guide/getting-started.md

@@ -0,0 +1,73 @@
+\page guide-getting-started Getting Started
+\brief Installation procedure and first application using this library
+
+This is a tutorial on how to use Jellyfin Qt library.
+
+## Project setup
+
+The library works as [a QML plugin](https://doc.qt.io/archives/qt-5.6/qqmlextensionplugin.html). 
+Compile the library, install it in the QML plugin path and add a qmldir file like this:
+
+```
+module nl.netsoj.chris.Jellyfin
+plugin JellyfinQt
+```
+
+You should then be able to import it in your QML files.
+
+
+```qml
+import nl.netsoj.chris.Jellyfin
+```
+
+\note
+In the documentation, the URI nl.netsoj.chris.Jellyfin will be used. 
+If you deviate from this, make sure to put the plugin in the correct location,
+as well as using the correct import statements in QML.
+
+## Hello Jellyfin!
+
+The first step for interacting with the library is setting up an \ref Jellyfin::ApiClient. 
+This object handles authentication. 
+
+
+
+\warning
+The way authentication works using ApiClient will change before the next major release to support multiple accounts! See \issue{4}
+
+Lets create an instance of ApiClient that is reachable from everywhere, by putting it in the ApplicationWindow:
+
+```qml
+import nl.netsoj.chris.Jellyfin as JF
+import QtQuick 2.0 as QQ
+
+QQ.ApplicationWindow {
+    readonly property JF.ApiClient apiClient: _apiClient
+
+    JF.ApiClient {
+        id: _apiClient
+        appName: "The name of your client"
+    }
+}
+```
+
+\note
+As an alternative, you could create a QML file only containing the ApiClient and [declaring it as a Singleton](https://doc.qt.io/archives/qt-5.6/qtqml-modules-qmldir.html#contents-of-a-module-definition-qmldir-file)
+
+## Authentication
+If the user already has logged in and the credentials are stored, this is quite easy: 
+the \ref Jellyfin::ApiClient::authenticated "authenticated" property will change to true and the corresponding signal will fire.
+You don't have to do anything else!
+
+When the user never has logged in, the signal \ref Jellyfin::ApiClient::setupRequired "setupRequired()" will be fired.
+When this happens, you should let the user enter a server URL and set it as the \ref Jellyfin::ApiClient::baseUrl "baseUrl" property.
+You can get a list model of servers in the local network using the \ref Jellyfin::ServerDiscoveryModel.
+
+After the \ref Jellyfin::ApiClient::baseUrl "baseUrl" property has been set, the slot \ref Jellyfin::ApiClient::authenticate "authenticate" should be called with an username and password.
+When authentication was successful, the property \ref Jellyfin::ApiClient::authenticated "authenticated" will be changed to true. 
+Otherwise, the signal \ref Jellyfin::ApiClient::authenticationError "authenticationError" will be fired.
+
+\note
+To show a list of available users, one can use the \ref Jellyfin::ViewModel::UserModel "UserModel" and \ref Jellyfin::ViewModel::PublicUsersLoader "PublicUsersLoader".
+However, this requires knowledge of the Loader and Model system, which will be explained in the next chapter \ref guide-apimodel-loader
+

core/doc/guides.md

@@ -0,0 +1,10 @@
+\page guides Usage guides
+
+\brief All guides intended for developers working with this library.
+
+All guides assume familiarity with QML. If you aren't, [the free online QML book](https://www.qt.io/product/qt6/qml-book) is a great place to start.
+Note that this book is written for Qt 6 QML, while this project is using Qt 5 QML.
+The differences between those versions are not large, so it still is a valuable resource.
+
+* \subpage guide-getting-started
+* \subpage guide-apimodel-loader

core/doc/mainpage.md

@@ -0,0 +1,11 @@
+\mainpage
+
+\note 
+This page is aimed at developers. If you are interested in using a Jellyfin application, please visit the [main website](https://heartfin.github.io/).
+
+This is the documentation page for the Jellyfin Qt library, a library for the [Qt framework](https://qt.io/) for interacting with the [Jellyfin media server](https://jellyfin.org).
+This project is not affiliated with the Jellyfin project.
+
+If you are planning on using this projects, see \ref guides for usage instructions and the reference documentation in the sidebar.
+
+If you'd like to contribute code, see \ref contributing for the process and style guidelines.

core/doc/namespace/dto.dox

@@ -0,0 +1,4 @@
+/**
+ * \namespace Jellyfin::DTO
+ * \brief Contains auto-generated Data Transfer Objects for the Jellyfin HTTP API
+ */

core/doc/namespace/viewmodel.dox

@@ -0,0 +1,4 @@
+/**
+ * \namespace Jellyfin::ViewModel
+ * \brief Contains all types exposed to QML
+ */