Merge pull request #5787 from akatsoulas/convert-mkdocs

Convert mkdocs

.github/workflows/publish-docs.yml

@@ -0,0 +1,28 @@
+name: Publish Docs in GitHub Pages
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

docs/api.md

@@ -0,0 +1,199 @@
+---
+title: API
+---
+
+SUMO has a series of API endpoints to access data.
+
+::: contents
+:::
+
+# Search suggest API
+
+Endpoint
+
+:   `/api/2/search/suggest/`
+
+Method
+
+:   `GET`
+
+Content type
+
+:   `application/json`
+
+Response
+
+:   `application/json`
+
+The search suggest API allows you to get back kb documents and aaq
+questions that match specified arguments.
+
+Arguments can be specified in the url querystring or in the HTTP request
+body.
+
+## Required arguments
+
+  ------------------------------------------------------------------------
+  argument         type     notes
+  ---------------- -------- ----------------------------------------------
+  q                string   This is the text you\'re querying for.
+
+  ------------------------------------------------------------------------
+
+## Optional arguments
+
++---------------+------+----------------------------------------------+
+| argument      | type | notes                                        |
++===============+======+==============================================+
+| locale        | st   | default: `settings.WIKI_DEFAULT_LANGUAGE`    |
+|               | ring |                                              |
+|               |      | The locale code to restrict results to.      |
+|               |      |                                              |
+|               |      | Examples:                                    |
+|               |      |                                              |
+|               |      | -   `en-US`                                  |
+|               |      | -   `fr`                                     |
++---------------+------+----------------------------------------------+
+| product       | st   | default: None                                |
+|               | ring |                                              |
+|               |      | The product to restrict results to.          |
+|               |      |                                              |
+|               |      | Example:                                     |
+|               |      |                                              |
+|               |      | -   `firefox`                                |
++---------------+------+----------------------------------------------+
+| max_documents | int  | default: 10                                  |
+|               | eger |                                              |
+|               |      | The maximum number of documents you want     |
+|               |      | back.                                        |
++---------------+------+----------------------------------------------+
+| max_questions | int  | default: 10                                  |
+|               | eger |                                              |
+|               |      | The maximum number of questions you want     |
+|               |      | back.                                        |
++---------------+------+----------------------------------------------+
+
+## Responses
+
+All response bodies are in JSON.
+
+### HTTP 200: Success
+
+With an HTTP 200, you\'ll get back a set of results in JSON.
+
+    {
+        "documents": [
+            {
+                "id": ...                  # id of kb article
+                "title": ...               # title of kb article
+                "url": ...                 # url of kb article
+                "slug": ...                # slug of kb article
+                "locale": ...              # locale of the article
+                "products": ...            # list of products for the article
+                "topics": ...              # list of topics for the article
+                "summary": ...             # paragraph summary of kb article (plaintext)
+                "html": ...                # html of the article
+            }
+            ...
+        ],
+        "questions": [
+            {
+                "id": ...                  # integer id of the question
+                "answers": ...             # list of answer ids
+                "content": ...             # content of question (in html)
+                "created": ...             # datetime stamp in iso-8601 format
+                "creator": ...             # JSON object describing the creator
+                "involved": ...            # list of JSON objects describing everyone who
+                                             participated in the question
+                "is_archived": ...         # boolean for whether this question is archived
+                "is_locked": ...           # boolean for whether this question is locked
+                "is_solved": ...           # boolean for whether this question is solved
+                "is_spam": ...             # boolean for whether this question is spam
+                "is_taken": ...            # FIXME:
+                "last_answer": ...         # id for the last answer
+                "num_answers": ...         # total number of answers
+                "locale": ...              # the locale for the question
+                "metadata": ...            # metadata collected for the question
+                "tags": ...                # tags for the question
+                "num_votes_past_week": ... # the number of votes in the last week
+                "num_votes": ...           # the total number of votes
+                "product": ...             # the product
+                "solution": ...            # id of answer marked as a solution if any
+                "taken_until": ...         # FIXME:
+                "taken_by": ...            # FIXME:
+                "title": ...               # title of the question
+                "topic": ...               # FIXME:
+                "updated_by": ...          # FIXME:
+                "updated": ...             # FIXME:
+            },
+            ...
+        ]
+    }
+
+## Examples
+
+Using curl:
+
+    curl -X GET "http://localhost:8000/api/2/search/suggest/?q=videos"
+
+    curl -X GET "http://localhost:8000/api/2/search/suggest/?q=videos&max_documents=3&max_questions=3"
+
+    curl -X GET "http://localhost:8000/api/2/search/suggest/" \
+         -H "Content-Type: application/json" \
+         -d '
+    {
+       "q": "videos",
+       "max_documents": 3,
+       "max_questions": 0
+    }'
+
+# Locales API
+
+> All locales supported by SUMO.
+>
+> **Example request**:
+>
+> ``` http
+> GET /api/2/locales/ HTTP/1.1
+> Accept: application/json
+> ```
+>
+> **Example response**:
+>
+> ``` http
+> HTTP/1.0 200 OK
+> Vary: Accept, X-Mobile, User-Agent
+> Allow: OPTIONS, GET
+> X-Frame-Options: DENY
+> Content-Type: application/json
+>
+> {
+>    "vi": {
+>       "name": "Vietnamese",
+>       "localized_name": "Ti\u1ebfng Vi\u1ec7t",
+>       "aaq_enabled": false
+>    },
+>    "el": {
+>       "name": "Greek",
+>       "localized_name": "\u0395\u03bb\u03bb\u03b7\u03bd\u03b9\u03ba\u03ac",
+>       "aaq_enabled": false
+>    },
+>    "en-US": {
+>       "name": "English",
+>       "localized_name": "English",
+>       "aaq_enabled": true
+>    }
+> }
+> ```
+>
+> reqheader Accept
+>
+> :   application/json
+>
+> resheader Content-Type
+>
+> :   application/json
+>
+> statuscode 200
+>
+> :   no error

docs/architectural-decisions.md

@@ -0,0 +1,12 @@
+---
+title: Architectural Decision Records
+---
+
+We record major architectural decisions for Kitsune/SUMO in Architecture
+Decision Records (ADR), as [described by Michael
+Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+Below is the list of our current ADRs.
+
+::: {.toctree maxdepth="1" glob=""}
+architecture/decisions/\*
+:::

docs/badges.md

@@ -0,0 +1,68 @@
+---
+title: Badges
+---
+
+::: warning
+::: title
+Warning
+:::
+
+This section of documentation may be outdated.
+:::
+
+Badges in kitsune are based off of [Django
+Badger](https://github.com/mozilla/django-badger),
+
+As of Q3 2018, kitsune issues four badges per calendar year:
+
+1.  KB Badge
+2.  L10n Badge
+3.  Support Forum Badge
+4.  Army of Awesome Badge
+
+A list of active badges can be seen at
+[https://support.mozilla.org/badges/](https://support.mozilla.org/en-US/badges/).
+
+# KB Badge & L10n Badge
+
+The KB Badge is awarded after a user has reached 10 approved English
+edits on knowledge base articles.
+
+The L10n Badge is awarded after a user has reached 10 approved
+translation edits on knowledge base articles.
+
+Logic for both badges can be found in `kitsune.wiki.badges`.
+
+The number of edits needed is configurable in
+`settings.BADGE_LIMIT_L10N_KB`.
+
+# Support Forum Badge
+
+The Support Forum Badge is awarded after a user has reached 30 support
+forum replies.
+
+Logic for awarding this badge can be found in
+`kitsune.questions.badges`.
+
+The number of replies needed is configurable in
+`settings.BADGE_LIMIT_SUPPORT_FORUM`.
+
+# Army of Awesome Badge
+
+::: warning
+::: title
+Warning
+:::
+
+This badge is no longer available.
+:::
+
+The Army of Awesome Badge is awarded when a user has tweeted 50 Army of
+Awesome replies.
+
+## Badge Creation
+
+Badges are either created manually through the Django Admin *or* created
+automatically via `get_or_create_badge` in `kitsune.kbadge.utils`.
+
+Creation through the Django Admin is the usual and preferred method.

docs/celery.md

@@ -0,0 +1,45 @@
+---
+title: Celery
+---
+
+Kitsune uses [Celery](http://celeryproject.org/) to enable offline task
+processing for long-running jobs like sending email notifications and
+re-rendering the Knowledge Base.
+
+Though Celery supports multiple message backends, we use
+[Redis](https://redis.io/).
+
+# When is Celery Appropriate
+
+You can use Celery to do any processing that doesn\'t need to happen in
+the current request-response cycle. Examples are generating thumbnails,
+sending out notification emails, updating content that isn\'t about to
+be displayed to the user, and others.
+
+Ask yourself the question: \"Is the user going to need this data on the
+page I\'m about to send them?\" If not, using a Celery task may be a
+good choice.
+
+# Configuring and Running
+
+Celery will automatically start when you run:
+
+    make run
+
+We set some reasonable defaults for Celery in `settings.py`. These can
+be overriden in `.env`.
+
+If you don\'t want to use Celery, you can set this in `.env`:
+
+    CELERY_TASK_ALWAYS_EAGER = True
+
+Setting this to `True` causes all task processing to be done online.
+This is useful when debugging tasks, for instance.
+
+You can also configure the concurrency. Here is the default:
+
+    CELERY_WORKER_CONCURRENCY = 4
+
+Then to restart the Celery workers, you just need to run:
+
+    docker-compose restart celery

docs/contactus.md

@@ -0,0 +1,26 @@
+---
+title: Contact us
+---
+
+# SUMO contributor forums
+
+If you\'re a SUMO contributor, then consider using the [contributor
+forums](https://support.mozilla.org/en-US/forums). This is the place for
+SUMO community discussions.
+
+# Kitsune hackers
+
+If you\'re hacking on the Kitsune code and have questions, ping us on
+[Matrix](https://wiki.mozilla.org/Matrix).
+
+We hang out in
+[#support-platform:mozilla.org](https://chat.mozilla.org/#/room/#support-platform:mozilla.org).
+
+If you ask something and all you get is silence, then it\'s probably the
+case that we\'re not around. Please try pinging us again.
+
+Current developers:
+
+-   Tasos Katsoulas (tasos)
+-   Ryan Johnson (ryan)
+-   Smith Ellis (smith)