Merge pull request #8 from Alqor-UG/4-add-documentation

Provide a first doc

.github/workflows/mkdocs.yml

@@ -0,0 +1,30 @@
+name: documentation
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy:
+    env:
+      CURRENT_VERSION: ${{ vars.CURRENT_VERSION }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0 # fetch all commits/branches
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - name: Install Dependencies
+        run: |
+          pipx install poetry
+          poetry install --only docs
+      - name: Configure Git user
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+      - name: Deploy with mike now 🚀
+        run: |
+          poetry run mike deploy $CURRENT_VERSION
+          poetry run mike set-default $CURRENT_VERSION
+          git push origin gh-pages

README.md

@@ -1,2 +1,47 @@
 # django-qlued
-A django package the couples together quantum hardware and endusers. 
+
+A django package the couples together quantum hardware and endusers. It allows cold atom hardware and simulators to be accessed through the `qiskit-cold-atom` and the `sqooler` SDK:
+
+- `qlued` handles the user management and stores the received *json* file in an appropiate queue.
+- `qiskit-cold-atom` allows the enduser to write the circuit definitions on its laptop and send them to the server in form of a nice *json* file.
+- `sqooler` acts as the SDK that pulls the the calculations from the queue and sends back the result into the storage.
+- end devices like the [sqooler-example](https://github.com/Alqor-UG/sqooler-example) or the [labscript-qc-example](https://github.com/Alqor-UG/labscript-qc-example) can perform the calculation and display it to the user.
+
+## Getting started
+
+You can currently install the package via pip through:
+
+```
+pip install git+https://github.com/Alqor-UG/django-qlued.git
+```
+
+We provide a template for a simple startup:
+
+- The fully deployable example is accessible via [qlued](https://github.com/Alqor-UG/qlued).
+- Examples for configurations can be found in the `tests` folder.
+
+
+## Contributing
+
+See [the contributing guide](docs/contributing.md) for detailed instructions on how to get started with a contribution to our project. We accept different **types of contributions**, most of them don't require you to write a single line of code.
+
+On the [qlued](https://alqor-ug.github.io/qlued/) site, you can click the make a contribution button at the top of the page to open a pull request for quick fixes like typos, updates, or link fixes.
+
+For more complex contributions, you can [open an issue](https://github.com/alqor-ug/qlued/issues) to describe the changes you'd like to see.
+
+If you're looking for a way to contribute, you can scan through our [existing issues](https://github.com/alqor-ug/qlued/issues) for something to work on. 
+
+### Join us in discussions
+
+We use GitHub Discussions to talk about all sorts of topics related to documentation and this site. For example: if you'd like help troubleshooting a PR, have a great new idea, or want to share something amazing you've learned in our docs, join us in the [discussions](https://github.com/alqor-ug/qlued/discussions).
+
+## License
+
+Any code within this repo is licenced under the [Apache 2](LICENSE) licence.
+
+The qlued documentation in the docs folders are licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0)](https://creativecommons.org/licenses/by-sa/4.0/).
+
+
+## Thanks :purple_heart:
+
+Thanks for all your contributions and efforts towards improving qlued. We thank you for being part of our :sparkles: community :sparkles:!

docs/api.md

@@ -0,0 +1,8 @@
+---
+comments: true
+---
+
+# Documentation of the API
+
+::: src.qlued.api_v2
+    handler: python

docs/contributing.md

@@ -0,0 +1,55 @@
+# Welcome to the qlued contributing guide
+
+Thank you for investing your time in potentially contributing to our project! Any contribution you make will be reflected on the repository of the open source project [qlued](https://github.com/alqor-ug/qlued/) :sparkles:.
+
+You can contribute to the **qlued**  content and site in several ways, which we will present you below. 
+
+## :mega: Discussions
+
+Discussions are where we have conversations.
+
+If you'd like help troubleshooting a qlued PR you're working on, have a great new idea, or want to share something amazing you've learned about quantum hardware access, join us in [discussions](https://github.com/alqor-ug/qlued/discussions/).
+
+## :lady_beetle: Issues
+[Issues](https://docs.github.com/en/github/managing-your-work-on-github/about-issues) are used to track tasks that contributors can help with. 
+
+If you've found something in the content or the code that should be updated, search open issues to see if someone else has reported the same thing. If it's something new, open an issue [here](https://github.com/alqor-ug/qlued/issues). We'll use the issue to have a conversation about the problem you want to fix.
+
+### Create a new issue
+
+If you spot a problem with the docs, search if an [issue already exists](https://github.com/alqor-ug/qlued/issues). If a related issue doesn't exist, you can open a [new issue](https://github.com/alqor-ug/qlued/issues/new).
+
+### Solve an issue
+
+Scan through our existing issues to find one that interests you. You can narrow down the search using labels as filters. See Labels for more information. As a general rule, we don’t assign issues to anyone. If you find an issue to work on, you are welcome to open a PR with a fix.
+
+### Make Changes in the github UI
+
+Click Make a contribution at the top of any page to make small changes such as a typo, sentence fix, or a broken link. This takes you to the .md file where you can make your changes and create a pull request for a review.
+
+### Commit your update
+Commit the changes once you are happy with them. Don't forget to self-review to speed up the review process :zap:.
+
+## :hammer_and_wrench: Pull requests
+A [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) is a way to suggest changes in our repository. When we merge those changes, they should be deployed to the live site almost immediately. :earth_africa:
+
+So when you're finished with the changes, create a pull request, also known as a PR.
+
+- Fill the description so that we can review your PR. This template helps reviewers understand your changes as well as the purpose of your pull request. 
+- Don't forget to [link PR to issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if you are solving one.
+- Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so the branch can be updated for a merge. Once you submit your PR, a **qlued** team member will review your proposal. We may ask questions or request additional information.
+- We may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
+- As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).
+- If you run into any merge issues, checkout this [git tutorial](https://github.com/skills/resolve-merge-conflicts) to help you resolve merge conflicts and other issues.
+
+### Your PR is merged!
+
+Congratulations :tada::tada: The **qlued** team thanks you :sparkles:. 
+
+Once your PR is merged, your contributions will be publicly visible on the [qlued repo](https://github.com/alqor-ug/qlued/). 
+
+Now you are part of the **qlued** community. Thank you for your contributions! We look forward to working with you to make our project even better.
+
+## Attribution
+
+These contribution guidelines are adapted from the contribution guidelines for Github docs, available online [on the github](https://github.com/github/docs/blob/main/CONTRIBUTING.md).

docs/index.md

@@ -0,0 +1,23 @@
+---
+comments: true
+---
+
+# Welcome to django-qlued
+
+*django-qlued* is a django package that allows you to submit jobs quantum various quantum hardware architectures. It is meant to be easily integrated in existing Django instances. For a deployabled example see [qlued](https://github.com/Alqor-UG/qlued).
+
+## Features
+- API based on the very efficient [django-ninja](https://django-ninja.dev/).
+- API fully compatible with [qiskit](https://qiskit.org/).
+- Safety features directly integrated through Django.
+- Easy to deploy in existing Django instances.
+- Full support for backends that integrate with [sqooler](https://github.com/alqor-ug/sqooler).
+
+## Our other projects projects
+* [``qlued``](https://github.com/alqor-ug/qlued) - template to deploy this package in a Django instance.
+* [``sqooler``](https://github.com/alqor-ug/sqooler) - Simulator backends.
+
+## Related projects
+
+* [``qiskit-cold-atom``](https://github.com/Qiskit-Extensions/qiskit-cold-atom) - QisKit examples.
+* depreceated expamples at [``pennylane-ls``](https://github.com/synqs/pennylane-ls) - Pennylane examples by synqs.

docs/overrides/partials/comments.html

@@ -0,0 +1,53 @@
+
+
+{% if page.meta.comments %}
+  <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
+<script src="https://giscus.app/client.js"
+        data-repo="alqor-ug/django-qlued"
+        data-repo-id="R_kgDOLBlJfA"
+        data-category="Show and tell"
+        data-category-id="DIC_kwDOLBlJfM4CcQt-"
+        data-mapping="pathname"
+        data-strict="0"
+        data-reactions-enabled="1"
+        data-emit-metadata="0"
+        data-input-position="top"
+        data-theme="preferred_color_scheme"
+        data-lang="en"
+        data-loading="lazy"
+        crossorigin="anonymous"
+        async>
+</script>
+
+  <!-- Synchronize Giscus theme with palette -->
+  <script>
+    var giscus = document.querySelector("script[src*=giscus]")
+
+    /* Set palette on initial load */
+    var palette = __md_get("__palette")
+    if (palette && typeof palette.color === "object") {
+      var theme = palette.color.scheme === "slate" ? "dark" : "light"
+      giscus.setAttribute("data-theme", theme) 
+
+
+    }
+
+    /* Register event handlers after documented loaded */
+    document.addEventListener("DOMContentLoaded", function() {
+      var ref = document.querySelector("[data-md-component=palette]")
+      ref.addEventListener("change", function() {
+        var palette = __md_get("__palette")
+        if (palette && typeof palette.color === "object") {
+          var theme = palette.color.scheme === "slate" ? "dark" : "light"
+
+          /* Instruct Giscus to change theme */
+          var frame = document.querySelector(".giscus-frame")
+          frame.contentWindow.postMessage(
+            { giscus: { setConfig: { theme } } },
+            "https://giscus.app"
+          )
+        }
+      })
+    })
+  </script>
+{% endif %}

mkdocs.yml

@@ -0,0 +1,34 @@
+site_name: qlued-django
+theme:
+  name: material
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.expand
+    - navigation.footer
+    - toc.follow
+
+  custom_dir: docs/overrides
+
+nav:
+  - Home: index.md
+  - Contributing: contributing.md
+  - API: api.md
+
+repo_url: https://github.com/alqor-ug/qlued-django
+edit_uri: edit/main/docs/
+
+extra:
+  version:
+    provider: mike
+
+plugins:
+- search
+- mkdocstrings
+
+markdown_extensions:
+  - toc
+  - attr_list
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences