From 048114f2f24120f61b7d92f0d79510a591a1a8d8 Mon Sep 17 00:00:00 2001 From: Hayden Date: Thu, 7 Jan 2021 15:25:01 -0900 Subject: [PATCH] imrpove api docs --- .github/workflows/build-docs.yml | 20 ++ docs/docs/api/api-examples.md | 5 + docs/docs/api/api-intro.md | 3 - docs/docs/api/demo/index.html | 26 +++ docs/docs/html/api.html | 26 +++ docs/mkdocs.yml | 4 +- .../components/RecipeEditor/PrintRecipe.vue | 198 ++++++++++++++++++ mealie/app.py | 12 +- mealie/models/backup_models.py | 23 +- mealie/routes/backup_routes.py | 20 +- mealie/routes/meal_routes.py | 5 +- mealie/settings.py | 1 + mealie/startup.py | 39 ++++ mealie/temp/api.html | 26 +++ mealie/utils/document_utils.py | 1 - scratch.json | 1 - 16 files changed, 387 insertions(+), 23 deletions(-) create mode 100644 .github/workflows/build-docs.yml create mode 100644 docs/docs/api/api-examples.md delete mode 100644 docs/docs/api/api-intro.md create mode 100644 docs/docs/api/demo/index.html create mode 100644 docs/docs/html/api.html create mode 100644 frontend/src/components/RecipeEditor/PrintRecipe.vue create mode 100644 mealie/temp/api.html delete mode 100644 mealie/utils/document_utils.py delete mode 100644 scratch.json diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 000000000000..3a7a0116e975 --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,20 @@ +name: Publish docs via GitHub Pages +on: + push: + branches: + - main + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - name: Checkout main + uses: actions/checkout@v1 + + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@master + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + CONFIG_FILE: docs/mkdocs.yml + EXTRA_PACKAGES: build-base \ No newline at end of file diff --git a/docs/docs/api/api-examples.md b/docs/docs/api/api-examples.md new file mode 100644 index 000000000000..3891caadaed9 --- /dev/null +++ b/docs/docs/api/api-examples.md @@ -0,0 +1,5 @@ +# API Examples + +TODO + +Have Ideas? Submit a PR! \ No newline at end of file diff --git a/docs/docs/api/api-intro.md b/docs/docs/api/api-intro.md deleted file mode 100644 index d32b02e08575..000000000000 --- a/docs/docs/api/api-intro.md +++ /dev/null @@ -1,3 +0,0 @@ -# API Introduction - -TODO \ No newline at end of file diff --git a/docs/docs/api/demo/index.html b/docs/docs/api/demo/index.html new file mode 100644 index 000000000000..7a1046cc7a85 --- /dev/null +++ b/docs/docs/api/demo/index.html @@ -0,0 +1,26 @@ + + + + + My Project - ReDoc + + + + + + + +
+ + + + + diff --git a/docs/docs/html/api.html b/docs/docs/html/api.html new file mode 100644 index 000000000000..7a1046cc7a85 --- /dev/null +++ b/docs/docs/html/api.html @@ -0,0 +1,26 @@ + + + + + My Project - ReDoc + + + + + + + +
+ + + + + diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 41646761ebd8..1f8a67812dd3 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -7,7 +7,6 @@ theme: logo: material/silverware-variant features: - navigation.expand - - navigation.instant markdown_extensions: - pymdownx.emoji: @@ -35,7 +34,8 @@ nav: - Backups and Exports: "getting-started/backups-and-exports.md" - Recipe Migration: "getting-started/migration-imports.md" - API Reference: - - Swagger/OpenAPI: "api/api-intro.md" + - API Documentation: "api/demo/index.html" + - Usage Examples: "api/api-examples.md" - Contributors Guide: - Non-Code: "contributors/non-coders.md" - Developers Guide: diff --git a/frontend/src/components/RecipeEditor/PrintRecipe.vue b/frontend/src/components/RecipeEditor/PrintRecipe.vue new file mode 100644 index 000000000000..6d742aa59bca --- /dev/null +++ b/frontend/src/components/RecipeEditor/PrintRecipe.vue @@ -0,0 +1,198 @@ + + + + + \ No newline at end of file diff --git a/mealie/app.py b/mealie/app.py index 0893c0eac2f1..8ff47ba54db3 100644 --- a/mealie/app.py +++ b/mealie/app.py @@ -1,5 +1,4 @@ from pathlib import Path -import os import uvicorn from fastapi import FastAPI @@ -15,8 +14,8 @@ from routes import ( static_routes, user_routes, ) -from routes.setting_routes import scheduler -from settings import PORT +from routes.setting_routes import scheduler # ! This has to be imported for scheduling +from settings import PORT, PRODUCTION from utils.logger import logger CWD = Path(__file__).parent @@ -26,10 +25,10 @@ app = FastAPI() # Mount Vue Frontend only in production -env = os.environ.get("ENV") -if(env == "prod"): +if PRODUCTION: app.mount("/static", StaticFiles(directory=WEB_PATH, html=True)) + # API Routes app.include_router(recipe_routes.router) app.include_router(meal_routes.router) @@ -49,6 +48,9 @@ app.include_router(static_routes.router) startup.ensure_dirs() startup.generate_default_theme() +# Generate API Documentation +if not PRODUCTION: + startup.generate_api_docs(app) if __name__ == "__main__": logger.info("-----SYSTEM STARTUP-----") diff --git a/mealie/models/backup_models.py b/mealie/models/backup_models.py index bfc590155023..3b023d7e996c 100644 --- a/mealie/models/backup_models.py +++ b/mealie/models/backup_models.py @@ -1,5 +1,5 @@ # from datetime import datetime -from typing import Optional +from typing import List, Optional from pydantic import BaseModel @@ -7,3 +7,24 @@ from pydantic import BaseModel class BackupJob(BaseModel): tag: Optional[str] template: Optional[str] + + class Config: + schema_extra = { + "example": { + "tag": "July 23rd 2021", + "template": "recipes.md", + } + } + + +class Imports(BaseModel): + imports: List[str] + templates: List[str] + + class Config: + schema_extra = { + "example": { + "imports": ["sample_data.zip", "sampe_data2.zip"], + "templates": ["recipes.md", "custom_template.md"], + } + } diff --git a/mealie/routes/backup_routes.py b/mealie/routes/backup_routes.py index f27526846455..8d93014b069b 100644 --- a/mealie/routes/backup_routes.py +++ b/mealie/routes/backup_routes.py @@ -1,14 +1,20 @@ from fastapi import APIRouter, HTTPException -from models.backup_models import BackupJob -from services.backup_services import (BACKUP_DIR, TEMPLATE_DIR, export_db, - import_from_archive) +from models.backup_models import BackupJob, Imports +from pydantic.main import BaseModel +from services.backup_services import ( + BACKUP_DIR, + TEMPLATE_DIR, + export_db, + import_from_archive, +) from utils.snackbar import SnackResponse router = APIRouter() -@router.get("/api/backups/available/", tags=["Import / Export"]) +@router.get("/api/backups/available/", tags=["Import / Export"], response_model=Imports) async def available_imports(): + """Returns a list of avaiable .zip files for import into Mealie.""" imports = [] templates = [] for archive in BACKUP_DIR.glob("*.zip"): @@ -17,12 +23,12 @@ async def available_imports(): for template in TEMPLATE_DIR.glob("*.md"): templates.append(template.name) - return {"imports": imports, "templates": templates} + return Imports(imports=imports, templates=templates) @router.post("/api/backups/export/database/", tags=["Import / Export"], status_code=201) async def export_database(data: BackupJob): - + """Generates a backup of the recipe database in json format.""" try: export_path = export_db(data.tag, data.template) except: @@ -38,6 +44,7 @@ async def export_database(data: BackupJob): "/api/backups/{file_name}/import/", tags=["Import / Export"], status_code=200 ) async def import_database(file_name: str): + """ Import a database backup file generated from Mealie. """ imported = import_from_archive(file_name) return imported @@ -48,6 +55,7 @@ async def import_database(file_name: str): status_code=200, ) async def delete_backup(backup_name: str): + """ Removes a database backup from the file system """ try: BACKUP_DIR.joinpath(backup_name).unlink() diff --git a/mealie/routes/meal_routes.py b/mealie/routes/meal_routes.py index f9ace57d1ec2..c8a51b3fb5d9 100644 --- a/mealie/routes/meal_routes.py +++ b/mealie/routes/meal_routes.py @@ -16,13 +16,10 @@ async def get_all_meals(): @router.post("/api/meal-plan/create/", tags=["Meal Plan"]) async def set_meal_plan(data: MealPlan): - """ Creates Mealplan from Frontend Data""" + """ Creates a mealplan database entry""" data.process_meals() data.save_to_db() - - # try: - # except: # raise HTTPException( # status_code=404, # detail=SnackResponse.error("Unable to Create Mealplan See Log"), diff --git a/mealie/settings.py b/mealie/settings.py index 5b3fb460d9c8..8a726d44efbe 100644 --- a/mealie/settings.py +++ b/mealie/settings.py @@ -8,6 +8,7 @@ ENV = CWD.joinpath(".env") dotenv.load_dotenv(ENV) # General +PRODUCTION = os.environ.get("ENV") PORT = int(os.getenv("mealie_port", 9000)) # Mongo Database diff --git a/mealie/startup.py b/mealie/startup.py index 70c2b3545ab3..706312cdb48e 100644 --- a/mealie/startup.py +++ b/mealie/startup.py @@ -1,3 +1,4 @@ +import json from pathlib import Path from services.settings_services import Colors, SiteTheme @@ -37,5 +38,43 @@ def generate_default_theme(): default_theme.save_to_db() +"""Script to export the ReDoc documentation page into a standalone HTML file.""" + +HTML_TEMPLATE = """ + + + + My Project - ReDoc + + + + + + + +
+ + + + +""" + +CWD = Path(__file__).parent +out_path = CWD.joinpath("temp", "api.html") + + +def generate_api_docs(app): + with open(out_path, "w") as fd: + print(HTML_TEMPLATE % json.dumps(app.openapi()), file=fd) + + if __name__ == "__main__": pass diff --git a/mealie/temp/api.html b/mealie/temp/api.html new file mode 100644 index 000000000000..ae3a97f5cf94 --- /dev/null +++ b/mealie/temp/api.html @@ -0,0 +1,26 @@ + + + + + My Project - ReDoc + + + + + + + +
+ + + + + diff --git a/mealie/utils/document_utils.py b/mealie/utils/document_utils.py deleted file mode 100644 index 576825f9264d..000000000000 --- a/mealie/utils/document_utils.py +++ /dev/null @@ -1 +0,0 @@ -import datetime diff --git a/scratch.json b/scratch.json deleted file mode 100644 index a80b55f1aab5..000000000000 --- a/scratch.json +++ /dev/null @@ -1 +0,0 @@ -// Test Notify \ No newline at end of file