mkdocs.yml

# yaml-language-server: $schema=https://json.schemastore.org/mkdocs-1.6.json
site_name: PrairieLearn Docs
site_url: https://docs.prairielearn.com/
repo_url: https://github.com/PrairieLearn/PrairieLearn
theme:
  name: material
  logo: assets/flower-square-nobg.svg
  custom_dir: docs/overrides
  favicon: assets/flower-square-256.png
  icon:
    repo: fontawesome/brands/github
    edit: material/pencil
    admonition:
      example: material/code-block-tags
    annotation: material/plus-circle
  palette:
    - scheme: default
      toggle:
        icon: material/brightness-7
        icon2: material/arrow-collapse
        name: Light mode, default width
      primary: custom
      accent: custom

    - scheme: slate
      toggle:
        icon: material/brightness-4
        icon2: material/arrow-collapse
        name: Dark mode, default width

    - scheme: default
      toggle:
        icon: material/brightness-7
        icon2: material/arrow-expand
        name: Light mode, full width
      media: full-width
      primary: custom
      accent: custom

    - scheme: slate
      toggle:
        icon: material/brightness-4
        icon2: material/arrow-expand
        name: Dark mode, full width
      media: full-width
  features:
    - navigation.sections
    - navigation.indexes
    - navigation.path
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.instant.progress
    - navigation.tracking
    - navigation.footer
    - navigation.indexes
    - search.suggest
    - content.action.edit
    - content.code.copy
    - content.tooltips
    # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations
    - content.code.annotate
    # https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs
    - content.tabs.link
plugins:
  - exclude:
      glob:
        - scripts/**
        - overrides/**
        - mkdocstrings/**
        - pyproject.toml
  - gen-files:
      scripts:
        - docs/scripts/gen_python_nav.py
        - docs/scripts/gen_additional_readmes.py
        - docs/scripts/gen_jsonschemas.py
  # Used for documenting our code with an autogenerated markdown file
  - literate-nav:
      implicit_index: true
  - search
  - d2:
      layout: dagre
      pad: 20
      theme: 0
  - mkdocstrings:
      custom_templates: docs/mkdocstrings
      default_handler: python
      handlers:
        python:
          paths:
            - graders/python/python_autograder
            - apps/prairielearn/python
          options:
            show_root_heading: false
            summary:
              attributes: false
              modules: true
            show_source: true
            show_bases: false # e.g. 'TypedDict'
            show_labels: true # e.g. 'instance-attribute'
            parameter_headings: false
            modernize_annotations: true # e.g. 'Optional[int]' -> 'int | None'
            show_docstring_examples: true # Examples:
            show_docstring_attributes: true # Attributes:
            docstring_section_style: table
            show_symbol_type_heading: false # class, meth, attr

            show_signature_annotations: true
            separate_signature: true
            signature_crossrefs: true
            show_if_no_docstring: false # ignore undocumented members
            show_overloads: false

            show_symbol_type_toc: true
            show_root_full_path: true # prairielearn.core
            show_root_toc_entry: false
            heading_level: 2
            group_by_category: false # e.g. 'classes', 'functions'
            members_order: alphabetical # source, alphabetical

          inventories:
            - url: https://numpy.org/doc/stable/objects.inv
            # Pandas docs has been unstable recently, which causes CI errors.
            # https://github.com/pandas-dev/pandas/issues/64584
            # - url: https://pandas.pydata.org/pandas-docs/stable/objects.inv
            - url: https://matplotlib.org/objects.inv
            - url: https://networkx.org/documentation/latest/objects.inv
            # - url: https://docs.sympy.org/latest/objects.inv # Doesn't seem to support ARM yet.
            - url: https://docs.python.org/3/objects.inv
              domains: [py, std, typing]
            - url: https://typing-extensions.readthedocs.io/en/latest/objects.inv
              domains: []
docs_dir: docs
# Fix "Edit on GitHub" link: (defaults to edit/master/docs/, note the s)
edit_uri: blob/master/docs/

markdown_extensions:
  # Allows us to use 2-space indents on lists, which is compatible with how
  # Prettier formats Markdown files.
  # https://pypi.org/project/mdx-truly-sane-lists/
  - mdx_truly_sane_lists

  # allows indented code blocks inside lists
  - pymdownx.superfences

  - tables
  # https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets
  - pymdownx.snippets:
      check_paths: true
  - pymdownx.details

  - toc:
      permalink: true
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/?h=pymdownx+blocks+caption#caption
  - pymdownx.blocks.caption
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/?h=attribute+list#attribute-lists
  - attr_list
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/?h=tabbed#tabbed
  - pymdownx.tabbed:
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  # https://squidfunk.github.io/mkdocs-material/reference/admonitions/
  - admonition
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#keys
  - pymdownx.keys
  # https://squidfunk.github.io/mkdocs-material/reference/icons-emojis
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

  - md_in_html
  # https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
  - pymdownx.betterem
  # https://facelessuser.github.io/pymdown-extensions/extensions/caret/
  - pymdownx.caret # h^2^o
  # https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
  - pymdownx.tilde # ~~deleted~~

extra_javascript:
  - assets/mathjax-config.js
  - https://cdn.jsdelivr.net/npm/mathjax@4/tex-svg.js
extra_css:
  - assets/extra.css

extra:
  # This section is consumed by the gen_additional_readmes.py script
  additional_readmes:
    - src: './contrib'
      dest: 'dev-guide/contrib/'
    - src: './apps/prairielearn/src/migrations/'
      dest: 'dev-guide/migrations/'
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/PrairieLearn/PrairieLearn
    - icon: fontawesome/brands/slack
      link: https://prairielearn.slack.com

nav:
  - Overview: 'index.md'
  - Getting started:
      - 'Getting started': 'getting-started/index.md'
      - 'Requesting your course space': 'requestCourse/index.md'
      - 'Concepts': 'concepts/index.md'
      - 'Workshop': 'workshop/index.md'
  - Student Guide:
      - 'Accessibility': 'student-guide/accessibility.md'
  - Instructor Guide:
      - instructor-guide/index.md
      - 'Installing and running locally': 'installing.md'
      - 'Editing and syncing course content': 'sync.md'
      # Hidden until the qti-content-import feature flag is generally available:
      # - 'Importing content from other platforms': 'importingContent.md'
      - 'Course configuration': 'course/index.md'
      - 'Course instances': 'courseInstance/index.md'
      - 'Assessments':
          - 'Overview': assessment/overview.md
          - 'Configuration': assessment/configuration.md
          - 'Access control': 'assessment/accessControl.md'
          # TODO: unhide once modern access control is generally available.
          # - 'Modern access control': 'assessment/accessControlModern.md'
          - 'Remote exams': 'assessment/remoteExams.md'
          - 'Regrading assessments': 'assessment/regrading.md'
      - 'Questions':
          - 'Overview': question/overview.md
          - '<code>question.html</code>': 'question/template.md'
          - '<code>server.py</code>': 'question/server.md'
          - 'Preferences': 'question/preferences.md'
          - 'Runtime environment': 'question/runtime.md'
          - 'Accessibility': 'question/accessibility.md'
      - 'Elements':
          - elements/index.md
          - '<span class="muted">pl-</span>answer-panel': 'elements/pl-answer-panel.md'
          - '<span class="muted">pl-</span>big-o-input': 'elements/pl-big-o-input.md'
          - '<span class="muted">pl-</span>card': 'elements/pl-card.md'
          - '<span class="muted">pl-</span>checkbox': 'elements/pl-checkbox.md'
          - '<span class="muted">pl-</span>code': 'elements/pl-code.md'
          - '<span class="muted">pl-</span>dataframe': 'elements/pl-dataframe.md'
          - '<span class="muted">pl-</span>drawing': 'pl-drawing/index.md'
          - '<span class="muted">pl-</span>excalidraw': 'elements/pl-excalidraw.md'
          - '<span class="muted">pl-</span>external-grader-results': 'elements/pl-external-grader-results.md'
          - '<span class="muted">pl-</span>external-grader-variables': 'elements/pl-external-grader-variables.md'
          - '<span class="muted">pl-</span>figure': 'elements/pl-figure.md'
          - '<span class="muted">pl-</span>file-download': 'elements/pl-file-download.md'
          - '<span class="muted">pl-</span>file-editor': 'elements/pl-file-editor.md'
          - '<span class="muted">pl-</span>file-preview': 'elements/pl-file-preview.md'
          - '<span class="muted">pl-</span>file-upload': 'elements/pl-file-upload.md'
          - '<span class="muted">pl-</span>graph': 'elements/pl-graph.md'
          - '<span class="muted">pl-</span>hidden-hints': 'elements/pl-hidden-hints.md'
          - '<span class="muted">pl-</span>hide-in-manual-grading': 'elements/pl-hide-in-manual-grading.md'
          - '<span class="muted">pl-</span>hide-in-panel': 'elements/pl-hide-in-panel.md'
          - '<span class="muted">pl-</span>image-capture': 'elements/pl-image-capture.md'
          - '<span class="muted">pl-</span>integer-input': 'elements/pl-integer-input.md'
          - '<span class="muted">pl-</span>manual-grading-only': 'elements/pl-manual-grading-only.md'
          - '<span class="muted">pl-</span>matching': 'elements/pl-matching.md'
          - '<span class="muted">pl-</span>matrix-component-input': 'elements/pl-matrix-component-input.md'
          - '<span class="muted">pl-</span>matrix-input': 'elements/pl-matrix-input.md'
          - '<span class="muted">pl-</span>matrix-latex': 'elements/pl-matrix-latex.md'
          - '<span class="muted">pl-</span>multiple-choice': 'elements/pl-multiple-choice.md'
          - '<span class="muted">pl-</span>number-input': 'elements/pl-number-input.md'
          - '<span class="muted">pl-</span>order-blocks': 'elements/pl-order-blocks.md'
          - '<span class="muted">pl-</span>overlay': 'elements/pl-overlay.md'
          - '<span class="muted">pl-</span>python-variable': 'elements/pl-python-variable.md'
          - '<span class="muted">pl-</span>question-panel': 'elements/pl-question-panel.md'
          - '<span class="muted">pl-</span>rich-text-editor': 'elements/pl-rich-text-editor.md'
          - '<span class="muted">pl-</span>sketch': 'elements/pl-sketch.md'
          - '<span class="muted">pl-</span>string-input': 'elements/pl-string-input.md'
          - '<span class="muted">pl-</span>submission-panel': 'elements/pl-submission-panel.md'
          - '<span class="muted">pl-</span>symbolic-input': 'elements/pl-symbolic-input.md'
          - '<span class="muted">pl-</span>template': 'elements/pl-template.md'
          - '<span class="muted">pl-</span>units-input': 'elements/pl-units-input.md'
          - '<span class="muted">pl-</span>variable-output': 'elements/pl-variable-output.md'
          - '<span class="muted">pl-</span>xss-safe': 'elements/pl-xss-safe.md'

      - 'clientFiles and serverFiles': 'clientServerFiles.md'
      - 'UUIDs in JSON files': 'uuid.md'
      - 'Docker images': 'dockerImages.md'
      - 'External grading': 'externalGrading.md'
      - 'Python autograder':
          - 'python-grader/index.md'
          - 'API reference': python-grader/reference-docs.md
      - 'C/C++ autograder': 'c-grader/index.md'
      - 'Java autograder': 'java-grader/index.md'
      - 'Python API reference':
          - python-reference/index.md
          - 'Colors': python-reference/prairielearn/colors.md
          - 'Conversion': python-reference/prairielearn/conversion_utils.md
          - 'HTML': python-reference/prairielearn/html_utils.md
          - 'Element extensions': python-reference/prairielearn/extension_utils.md
          - 'Grading': python-reference/prairielearn/grading_utils.md
          - 'Questions': python-reference/prairielearn/question_utils.md
          - 'Numerical precision': python-reference/prairielearn/to_precision.md
          - 'Other': python-reference/prairielearn/misc_utils.md
          - 'SymPy': python-reference/prairielearn/sympy_utils.md
          - 'Timeouts': python-reference/prairielearn/timeout_utils.md
      - 'Workspaces': 'workspaces/index.md'
      - 'Manual grading': 'manualGrading/index.md'
      - 'AI grading': 'aiGrading/index.md'
      - 'Content sharing': 'contentSharing.md'
      - 'What to tell students': 'whatToTellStudents.md'
      - 'FAQ': 'faq.md'
      - 'API': 'api.md'
      - 'LMS Integration': 'lmsIntegrationInstructor.md'
      - 'Schema Reference':
          - '<code class="doc-symbol doc-symbol-nav doc-symbol-json"></code> Course': schemas/infoCourse.md
          - '<code class="doc-symbol doc-symbol-nav doc-symbol-json"></code> Question': schemas/infoQuestion.md
          - '<code class="doc-symbol doc-symbol-nav doc-symbol-json"></code> Assessment': schemas/infoAssessment.md
          - '<code class="doc-symbol doc-symbol-nav doc-symbol-json"></code> Course Instance': schemas/infoCourseInstance.md
          - '<code class="doc-symbol doc-symbol-nav doc-symbol-json"></code> Element': schemas/infoElementCore.md
          - '<code class="doc-symbol doc-symbol-nav doc-symbol-json"></code> Element (Course)': schemas/infoElementCourse.md
          - '<code class="doc-symbol doc-symbol-nav doc-symbol-json"></code> Element Extension': schemas/infoElementExtension.md
  - 'Developer Guide':
      - dev-guide/index.md
      - 'Running in Docker': dev-guide/installingLocal.md
      - dev-guide/installingNative.md
      - 'Quickstart': dev-guide/quickstart.md
      - dev-guide/guide.md
      - 'Migrations': 'dev-guide/migrations/'
      - 'Server configuration': 'dev-guide/configJson.md'
      - 'Building question elements': 'devElements.md'
      - 'Building element extensions': 'elementExtensions.md'
      - 'Code execution': 'codeExecution.md'
      - 'Contributing': 'contributing.md'
      - 'Utility scripts': 'dev-guide/contrib/'
  - Administrators:
      - 'SAML SSO configuration': 'saml.md'
      - 'LTI 1.3 configuration': 'lti13.md'
  - Running in Production:
      - 'Setup': 'running-in-production/setup.md'
      - 'Using Docker Compose': 'running-in-production/docker-compose.md'
      - 'User Authentication': 'running-in-production/authentication.md'
      - 'Admin User': 'running-in-production/admin-user.md'
  - Deprecated Features:
      - 'Old v1/v2 question format': 'oldQuestion.md'
      - 'Old PrairieDraw graphics': 'PrairieDraw.md'

not_in_nav: |
  workshop/lesson1.md
  workshop/lesson2.md
  workshop/lesson3.md
  workshop/lesson4.md
  workshop/lesson5.md
  schemas/questionOptionsCalculation.md
  schemas/questionOptionsCheckbox.md
  schemas/questionOptionsFile.md
  schemas/questionOptionsMultipleChoice.md
  schemas/questionOptionsMultipleTrueFalse.md
  schemas/questionOptionsv3.md
  elements/pl-prairiedraw-figure.md
  elements/pl-dropdown.md
  elements/pl-variable-score.md
  dev-guide/contrib/*
  assessment/accessControlModern.md
  importingContent.md

validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn
  anchors: warn

watch:
  - apps/prairielearn/python

hooks:
  - docs/scripts/d2_svg_file.py
  - docs/scripts/jsonschema_details_fix.py