Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): markdown linting and improved documentation #902

Conversation

justinthelaw
Copy link
Contributor

@justinthelaw justinthelaw commented Aug 12, 2024

OVERVIEW

An overhaul of the developer workflow. Updates to website documentation (UDS bundle latest, requirements, system specs), developer documentation (repo only) and workflows.

Secondary effects include standardizing language across the repository, README sections and wording, and making fixes to Makefile functionality and standardization (Makefile -> UDS Tasks, later), adding developer dependencies into sub-directories' pyproject.toml that are missing them.

NEW

  • Markdown linting pre-commit
  • Markdown linting workflow
  • Markdown lint central configuration
  • DEVELOPMENT.md
    • Adds additional pre-requisites, tips and tricks, and troubleshooting
  • CODE_OF_CONDUCT.md
  • SECURITY.md

UPDATED

  • Documentation website
    • System specifications reviewed and updated for UDS bundle latest deployments only
    • Pre-requisites reviewed, updated and trimmed for UDS bundle latest deployments only
    • All developer docs moved to GitHub (e.g., UDS bundle dev, local Python and Typescript, etc.)
    • Added accepted file formats for Translate, Transcribe, and Files endpoints
  • CONTRIBUTING.md
    • Adds instructions for pre-commit
    • Updates language (e.g., remove mentions of Zarf)
    • Specifies conventional commits
  • Pre-commit
    • Re-organizes original pre-commits
    • Adds standard, default pre-commit hooks
  • Makefiles
    • Simplifies and standardizes usage of Makefiles across directories
    • Fixes broken or incorrect Make targets/commands
  • Standardized flow and language in docs
    • "LeapfrogAI" is used everywhere (e.g., no more "Leapfrog", "LeapfrogAPI", "Leapfrog AI", etc.)
    • All READMEs follow a standardized flow, only varying for special use cases
    • pyproject.toml missing developer dependencies that are assumed installed

@justinthelaw justinthelaw added the documentation Improvements or additions to documentation label Aug 12, 2024
@justinthelaw justinthelaw self-assigned this Aug 12, 2024
Copy link

netlify bot commented Aug 12, 2024

Deploy Preview for leapfrogai-docs ready!

Name Link
🔨 Latest commit 5fc2b38
🔍 Latest deploy log https://app.netlify.com/sites/leapfrogai-docs/deploys/66c38496277d5800073f7966
😎 Deploy Preview https://deploy-preview-902--leapfrogai-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 43 (🟢 up 3 from production)
Accessibility: 98 (no change from production)
Best Practices: 100 (no change from production)
SEO: 92 (no change from production)
PWA: -
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

@justinthelaw justinthelaw marked this pull request as ready for review August 15, 2024 16:45
@justinthelaw justinthelaw requested a review from a team as a code owner August 15, 2024 16:45
@justinthelaw
Copy link
Contributor Author

For seeing the preview of the docs website, and use this every time you see a ref to the docs website during your review: https://deploy-preview-902--leapfrogai-docs.netlify.app/

For viewing the Markdowns uninterrupted: https://github.com/defenseunicorns/leapfrogai/tree/711-754-579-578-571-567-332-markdown-linting-and-improved-documentation

packages/vllm/README.md Outdated Show resolved Hide resolved
packages/vllm/README.md Outdated Show resolved Hide resolved
website/content/en/docs/local-deploy-guide/dependencies.md Outdated Show resolved Hide resolved
website/content/en/docs/local-deploy-guide/dependencies.md Outdated Show resolved Hide resolved
docs/DEVELOPMENT.md Show resolved Hide resolved
packages/k3d-gpu/README.md Show resolved Hide resolved
website/hugo.toml Outdated Show resolved Hide resolved
tests/README.md Outdated Show resolved Hide resolved
Copy link
Contributor

@unicorn-kp unicorn-kp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed documentation, not changes to the makefiles or any of the code.

packages/k3d-gpu/README.md Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
@justinthelaw justinthelaw merged commit 046a466 into main Aug 19, 2024
24 checks passed
@justinthelaw justinthelaw deleted the 711-754-579-578-571-567-332-markdown-linting-and-improved-documentation branch August 19, 2024 18:38

:key: == Required by automation

1. Drop a comment in any issue to let everyone know you're working on it and submit a Draft PR (step 4) as soon as you are able.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If allowed with the repository permissions, should they assign themselves to the issue as well?


5. :key: Automated tests will begin based on the paths you have edited in your Pull Request.

> ⚠️ **NOTE:** _If you are an external third-party contributor, the pipelines won't run until a [CODEOWNER](./CODEOWNERS) approves the pipeline run._
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How should contributors request this approval?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
7 participants