diff --git a/.github/ISSUE_TEMPLATE/BUG.yaml b/.github/ISSUE_TEMPLATE/BUG.yaml new file mode 100644 index 0000000..d97e00b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/BUG.yaml @@ -0,0 +1,83 @@ +name: "Bug Report" +description: Create an issue for a bug. +title: "Bug: " +labels: ["bug", "triage required"] +body: + - type: textarea + id: description + attributes: + label: "Description" + description: Please enter an description of the bug you are encountering + placeholder: + validations: + required: true + - type: input + id: reprod-url + attributes: + label: "URL to code causing the issue" + description: Please enter the URL to provide a reproduction of the issue, if applicable + placeholder: ex. https://github.com/USERNAME/REPO-NAME + validations: + required: false + - type: textarea + id: mcve + attributes: + label: "MCVE" + description: "Please provide a minimal, complete, and verifiable example of the issue." + value: | + ```py + # Your MCVE code here + ``` + render: python + validations: + required: false + - type: textarea + id: reprod + attributes: + label: "Steps to reproduce" + description: Please enter the exact steps to reproduce the issue + value: | + 1. Go to '...' + 2. Click on '....' + 3. Scroll down to '....' + 4. See error + render: bash + validations: + required: false + - type: textarea + id: screenshot + attributes: + label: "Screenshots" + description: If applicable, add screenshots to help explain your problem. + value: | + "![SCREENSHOT_DESCRIPTION](SCREENSHOT_LINK.png)" + render: bash + validations: + required: false + - type: textarea + id: logs + attributes: + label: "Logs" + description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. + render: bash + validations: + required: false + - type: textarea + id: version + attributes: + label: "Project Version" + description: What version of the project are you using when encountering this issue? + validations: + required: true + - type: checkboxes + id: platform + attributes: + label: "Platform" + description: What platform are you encountering the issue on? + options: + - label: "Linux" + - label: "Mac" + - label: "Windows" + - label: "Other (Please specify in the description above)" + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/DOCS.yaml b/.github/ISSUE_TEMPLATE/DOCS.yaml new file mode 100644 index 0000000..02b4dd0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/DOCS.yaml @@ -0,0 +1,13 @@ +name: "Documentation Update" +description: Create an issue for documentation changes +title: "Docs: <title>" +labels: ["documentation"] +body: + - type: textarea + id: summary + attributes: + label: "Summary" + description: Provide a brief summary of your feature request + placeholder: Describe in a few lines your feature request + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/REQUEST.yaml b/.github/ISSUE_TEMPLATE/REQUEST.yaml new file mode 100644 index 0000000..90446af --- /dev/null +++ b/.github/ISSUE_TEMPLATE/REQUEST.yaml @@ -0,0 +1,37 @@ +name: "Feature Request" +description: Create an issue for a new feature request +title: "Enhancement: <title>" +labels: ["enhancement"] +body: + - type: textarea + id: summary + attributes: + label: "Summary" + description: Provide a brief summary of your feature request + placeholder: Describe in a few lines your feature request + validations: + required: true + - type: textarea + id: basic_example + attributes: + label: "Basic Example" + description: Indicate here some basic examples of your feature. + placeholder: Provide some basic example of your feature request + validations: + required: false + - type: textarea + id: drawbacks + attributes: + label: "Drawbacks and Impact" + description: What are the drawbacks or impacts of your feature request? + placeholder: Describe any the drawbacks or impacts of your feature request + validations: + required: false + - type: textarea + id: unresolved_question + attributes: + label: "Unresolved questions" + description: What, if any, unresolved questions do you have about your feature request? + placeholder: Identify any unresolved issues. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yaml b/.github/ISSUE_TEMPLATE/config.yaml new file mode 100644 index 0000000..3ba13e0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yaml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/dependabot.yaml b/.github/dependabot.yaml new file mode 100644 index 0000000..1230149 --- /dev/null +++ b/.github/dependabot.yaml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "daily" diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 0000000..57f88fc --- /dev/null +++ b/.github/workflows/ci.yaml @@ -0,0 +1,90 @@ +name: Tests and Linting + +on: + pull_request: + push: + branches: + - main + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v4 + with: + python-version: "3.11" + + - name: Install Pre-Commit + run: python -m pip install pre-commit && pre-commit install + + - name: Load cached Pre-Commit Dependencies + id: cached-pre-commit-dependencies + uses: actions/cache@v3 + with: + path: ~/.cache/pre-commit/ + key: pre-commit-|${{ env.pythonLocation }}|${{ hashFiles('.pre-commit-config.yaml') }} + + - name: Execute Pre-Commit + run: pre-commit run --show-diff-on-failure --color=always --all-files + + test: + strategy: + fail-fast: true + matrix: + python-version: ["3.8", "3.9", "3.10", "3.11"] + uses: ./.github/workflows/test.yaml + with: + python-version: ${{ matrix.python-version }} + coverage: ${{ matrix.python-version == '3.11' }} + + test-platform-compat: + if: github.event_name == 'push' + strategy: + fail-fast: true + matrix: + os: ["macos-latest", "windows-latest"] + uses: ./.github/workflows/test.yaml + with: + python-version: "3.11" + os: ${{ matrix.os }} + + sonar: + needs: + - test + - validate + if: github.event.pull_request.head.repo.fork == false && github.repository_owner == 'litestar-org' + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + - name: Download Artifacts + uses: actions/download-artifact@v3 + with: + name: coverage-xml + - name: Fix coverage file for sonarcloud + run: sed -i "s/home\/runner\/work\/litestar\/litestar/github\/workspace/g" coverage.xml + - name: SonarCloud Scan + uses: sonarsource/sonarcloud-github-action@master + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} + + codeql: + needs: + - test + - validate + runs-on: ubuntu-latest + permissions: + security-events: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + - name: Initialize CodeQL Without Dependencies + uses: github/codeql-action/init@v2 + with: + setup-python-dependencies: false + languages: python + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..ed42fa8 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,22 @@ +name: Scheduled CodeQL + +on: + schedule: + - cron: "0 4 * * *" + +jobs: + codeql: + runs-on: ubuntu-latest + permissions: + security-events: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + ref: "main" + + - name: Initialize CodeQL With Dependencies + uses: github/codeql-action/init@v2 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..64c5561 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,38 @@ +name: Documentation Building + +on: + release: + types: [published] + +jobs: + docs: + permissions: + contents: write + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v4 + with: + python-version: "3.11" + + - uses: pdm-project/setup-pdm@v3 + name: Set up PDM + with: + python-version: "3.11" + allow-python-prereleases: true + cache: true + + - name: Install dependencies + run: pdm install + + - name: Fetch gh pages + run: git fetch origin gh-pages --depth=1 + + - name: Build docs + run: pdm run python tools/build_docs.py docs-build + + - name: Deploy + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs-build diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 0000000..7984ba6 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,54 @@ +:root { + --brand-primary: #4b8bbe; + --brand-primary-rgb: 75, 139, 190; + + --brand-secondary: #ffe873; + --brand-secondary-rgb: 255, 232, 115; + + --brand-dark-blue: #306998; + --brand-dark-blue-rgb: 48, 105, 152; + + --brand-yellow: #ffd43b; + --brand-yellow-rgb: 255, 212, 59; + + --brand-dark: #646464; + --brand-dark-rgb: 100, 100, 100; + + --brand-light: #ebdddd; + --brand-light-rgb: 235, 221, 221; +} + +html.dark, +html.light { + --sd-color-tabs-label-hover: var(--brand-secondary); +} + +html.light { + --syntax-light-constant: var(--brand-primary); + --syntax-light-meta: var(--brand-primary); + /* --syntax-light-text: #09090a;*/ + /* --syntax-light-cap-bg: #325b76;*/ + /* --syntax-light-pre-bg: #ddefff;*/ + --syntax-light-keyword: var(--brand-primary); + --syntax-light-property: var(--brand-dark); +} + +html.light .yue { + --yue-c-code-bg: var(--brand-yellow) !important; + --yue-c-code: var(--brand-dark) !important; + /*--yue-c-black: #11a1ff !important;*/ +} + +html.dark { + --syntax-dark-keyword: var(--brand-primary); + --syntax-dark-property: var(--brand-secondary); + --syntax-dark-constant: var(--brand-primary); + --syntax-dark-meta: var(--brand-primary); + --syntax-dark-pre-bg: rgba(var(--brand-primary-rgb), 0.1); +} + +html.dark .yue { + --yue-c-code-bg: var(--brand-dark) !important; + --yue-c-code: var(--brand-secondary) !important; + /*--yue-c-black: #11a1ff !important;*/ +} diff --git a/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 0000000..d54c45c Binary files /dev/null and b/docs/_static/logo.png differ diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..5a0646d --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,11 @@ +============= +API Reference +============= + +.. toctree:: + :titlesonly: + :caption: API Reference Documentation + :glob: + :hidden: + + widgets/index \ No newline at end of file diff --git a/docs/api/widgets/index.rst b/docs/api/widgets/index.rst new file mode 100644 index 0000000..15a72e5 --- /dev/null +++ b/docs/api/widgets/index.rst @@ -0,0 +1,6 @@ +======= +widgets +======= + +.. automodule:: src.widgets.events + :members: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..cf675f5 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,150 @@ +# Configuration file for the Sphinx documentation builder. +import os + +from src.__metadata__ import __project__ as project +from src.__metadata__ import __version__ as version + +# -- Environmental Data ------------------------------------------------------ + + +# -- Project information ----------------------------------------------------- +project = project +author = "Jolt Org" +release = os.getenv("_PYTHON-REDDIT_DOCS_BUILD_VERSION", version.rsplit(".")[0]) +copyright = "2023, Python Reddit" + +# -- General configuration --------------------------------------------------- +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.autosectionlabel", + "sphinx.ext.githubpages", + "sphinx.ext.viewcode", + "sphinx.ext.intersphinx", + "sphinx_copybutton", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinx_toolbox.collapse", + "sphinx_design", +] + +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), +} +PY_CLASS = "py:class" +PY_RE = r"py:.*" +PY_METH = "py:meth" +PY_ATTR = "py:attr" +PY_OBJ = "py:obj" + +nitpicky = True +nitpick_ignore = [ + # external library / undocumented external + (PY_CLASS, "ExternalType"), + (PY_CLASS, "TypeEngine"), + (PY_CLASS, "UserDefinedType"), + (PY_CLASS, "_types.TypeDecorator"), + (PY_METH, "_types.TypeDecorator.process_bind_param"), + (PY_METH, "_types.TypeDecorator.process_result_value"), + (PY_METH, "type_engine"), + # type vars and aliases / intentionally undocumented + (PY_CLASS, "CollectionT"), + (PY_CLASS, "EmptyType"), + (PY_CLASS, "ModelT"), + (PY_CLASS, "T"), + (PY_CLASS, "AsyncSession"), + (PY_CLASS, "Select"), +] +nitpick_ignore_regex = [ +] + +napoleon_google_docstring = True +napoleon_include_special_with_doc = True +napoleon_use_admonition_for_examples = True +napoleon_use_admonition_for_notes = True +napoleon_use_admonition_for_references = False +napoleon_attr_annotations = True + +autoclass_content = "class" +autodoc_class_signature = "separated" +autodoc_default_options = {"special-members": "__init__", "show-inheritance": True, "members": True} +autodoc_member_order = "bysource" +autodoc_typehints_format = "short" +autodoc_type_aliases = {"FilterTypes": "FilterTypes"} + +autosectionlabel_prefix_document = True + +todo_include_todos = True + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# -- Style configuration ----------------------------------------------------- +html_theme = "shibuya" +html_static_path = ["_static"] +html_css_files = ["css/custom.css"] +html_show_sourcelink = True +html_title = "Docs" +html_favicon = "_static/logo.png" +html_logo = "_static/logo.png" +html_context = { + "source_type": "github", + "source_user": "python-reddit", + "source_repo": project.replace("_", "-"), +} + +brand_colors = { + "--brand-primary": {"rgb": "75, 139, 190", "hex": "#4b8bbe"}, + "--brand-secondary": {"rgb": "255, 232, 115", "hex": "#ffe873"}, + "--brand-dark-blue": {"rgb": "48, 105, 152", "hex": "#306998"}, + "--brand-yellow": {"rgb": "255, 212, 59", "hex": "#ffd43b"}, + "--brand-dark": {"rgb": "100, 100, 100", "hex": "#646464"}, + "--brand-light": {"rgb": "235, 221, 221", "hex": "#ebdddd"}, +} + + +html_theme_options = { + "logo_target": "/", + "announcement": "This documentation is currently under development.", + "github_url": "https://github.com/python-reddit/python", + "nav_links": [ + {"title": "Home", "url": "https://python-reddit.github.io/python"}, + {"title": "Docs", "url": "https://python-reddit.github.io/python"}, + {"title": "Code", "url": "https://github.com/python-reddit/python"}, + ], + "light_css_variables": { + # RGB + "--sy-rc-theme": brand_colors["--brand-primary"]["rgb"], + "--sy-rc-text": brand_colors["--brand-primary"]["rgb"], + "--sy-rc-invert": brand_colors["--brand-primary"]["rgb"], + # "--sy-rc-bg": brand_colors["--brand-secondary"]["rgb"], + # Hex + "--sy-c-link": brand_colors["--brand-secondary"]["hex"], + # "--sy-c-foot-bg": "#191919", + "--sy-c-foot-divider": brand_colors["--brand-primary"]["hex"], + "--sy-c-foot-text": brand_colors["--brand-dark"]["hex"], + "--sy-c-bold": brand_colors["--brand-primary"]["hex"], + "--sy-c-heading": brand_colors["--brand-primary"]["hex"], + "--sy-c-text-weak": brand_colors["--brand-primary"]["hex"], + "--sy-c-text": brand_colors["--brand-dark"]["hex"], + "--sy-c-bg-weak": brand_colors["--brand-dark"]["rgb"], + }, + "dark_css_variables": { + # RGB + "--sy-rc-theme": brand_colors["--brand-primary"]["rgb"], + "--sy-rc-text": brand_colors["--brand-primary"]["rgb"], + "--sy-rc-invert": brand_colors["--brand-primary"]["rgb"], + "--sy-rc-bg": brand_colors["--brand-dark"]["rgb"], + # Hex + "--sy-c-link": brand_colors["--brand-primary"]["hex"], + "--sy-c-foot-bg": brand_colors["--brand-dark"]["hex"], + "--sy-c-foot-divider": brand_colors["--brand-primary"]["hex"], + "--sy-c-foot-text": brand_colors["--brand-light"]["hex"], + "--sy-c-bold": brand_colors["--brand-primary"]["hex"], + "--sy-c-heading": brand_colors["--brand-primary"]["hex"], + "--sy-c-text-weak": brand_colors["--brand-primary"]["hex"], + "--sy-c-text": brand_colors["--brand-light"]["hex"], + "--sy-c-bg-weak": brand_colors["--brand-dark"]["hex"], + "--sy-c-bg": brand_colors["--brand-primary"]["hex"], + }, +} diff --git a/docs/contribution-guide.rst b/docs/contribution-guide.rst new file mode 100644 index 0000000..bbd440e --- /dev/null +++ b/docs/contribution-guide.rst @@ -0,0 +1,3 @@ +:orphan: + +.. include:: ../CONTRIBUTING.rst diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..19ab1f5 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,26 @@ +============= +Python Reddit +============= + +Overview +-------- + +This project helps manage the Python subreddit. + + +Usage +----- + +.. toctree:: + :titlesonly: + :caption: Docs + :hidden: + + api/index + +.. toctree:: + :titlesonly: + :caption: Development + :hidden: + + contribution-guide