Open fyliu opened 5 months ago
Question: I'm not sure what milestone to use for this. Seems like it should be before All Tables Added. I was thinking Compliance, but I looked it up and it doesn't seem to fit there.
Other than that, this is ready to be prioritized.
Django REST Swagger https://django-rest-swagger.readthedocs.io/en/latest/ made directly for Django rest framework
@drakeredwind01 that's the same functionality that drf-spectacular provides. You have to be running the server to view it and it's also not integrated into the mkdocs site we have in ghpages.
What we're hoping for is something like a mkdocs plugin that generates a page for mkdocs with the same information.
Warnings for Broken Links: Sphinx excels at identifying broken links within your documentation. When an anchor (reference point within a document) no longer exists, Sphinx generates warnings during the build process. This proactive approach helps maintain accurate and up-to-date documentation, a crucial aspect for a complex project like the Linux kernel. Why Sphinx is Superior to the Alternatives:
mkdocs-swagger-ui-tag & 2. mkdocs-render-swagger-plugin: These plugins are specifically designed for building API documentation with Swagger/OpenAPI specifications. While useful for API docs, they lack the versatility of Sphinx.
Sphinx can handle various content types beyond APIs, including text, code listings, and images – perfect for the diverse nature of the Linux kernel documentation. mkdocs-openapi: Similar to the previous options, mkdocs-openapi caters primarily to API documentation. While it can handle OpenAPI specifications, Sphinx offers broader functionality.
OpenAPI Docs: OpenAPI Docs likely refers to the official tooling for generating documentation directly from OpenAPI specs. While efficient, it might lack the customization options Sphinx provides.
Sphinx allows tailoring the documentation layout, branding, and inclusion of additional content beyond the pure API specifications. mkdocs-swagger-ui: Another plugin focused on API documentation with Swagger UI integration. It falls short of Sphinx's versatility.
Primary Functionality | Content Types Supported | Link Checking | Customization | Community & Ecosystem | Cross-Platform Support | |
---|---|---|---|---|---|---|
Sphinx | General Documentation | Text, Code, Images, Tables, etc. | Warns about broken anchors | Extensive customization options (themes, plugins) | Large community, extensive plugins and themes | Yes |
mkdocs-swagger-ui-tag | API Documentation (Swagger UI) | OpenAPI Specifications | No | Limited customization | Smaller community, fewer plugins | Yes |
mkdocs-render-swagger-plugin | API Documentation (Swagger UI) | OpenAPI Specifications | No | Limited customization | Smaller community, fewer plugins | Yes |
mkdocs-openapi | API Documentation (OpenAPI) | OpenAPI Specifications | No | Limited customization | Smaller community, fewer plugins | Yes |
OpenAPI Docs | API Documentation (OpenAPI) | OpenAPI Specifications | No | Limited customization | Official tooling, limited community support | Yes |
mkdocs-swagger-ui | API Documentation (Swagger UI) | OpenAPI Specifications | No | Limited customization | Smaller community, fewer plugins | Yes |
@drakeredwind01 Sphinx doesn't have the functionality to satisfy the main requirement in this issue which is to generate API docs.
I think my comment didn't address the context of your topic. My comment was in the context of this issue's requirements: adding OpenAPI docs to our documentation. Your topic is a broader one that we've covered before in this project: documentation generators. But your comparison is also apples to oranges. Sphinx is a documentation system and the others are MkDocs plugins. Sphinx vs. MkDocs would be the same level comparison.
Note that this project is currently using MkDocs and there's already pages written with MkDocs-specific markup.
For historical context, we've compared documentation generator systems in the past, including Sphinx, Asciidoc, and MkDocs, weighed our needs and organization needs, and settled on MkDocs. I was the one wanting to adopt Sphinx at the time. I have an older documentation site set up here, with this page showing some of the UI enhancements it provides over Github markdown. This is our docs with similar enhancements in MkDocs (some of it still in PR). The organizational needs part was that hackforla needed to choose a system for all its projects, not just for peopledepot, and wanted to link them up in the future. So while Sphinx was slightly better for us as a python project, MkDoc was a much better choice for other projects.
This is why I mentioned ease of integration as a dimension to compare. If it involves adding an entire documentation system or replacing our current one and converting all our existing documentation files to it, that's a big hurdle to integration. If it's an independent generator that just outputs a webpage into the gh-pages branch where the document is hosted, that might be a viable solution. This is why MkDocs plugins are more favored. I was thinking maybe there's some independent generator out there that could also work, but Sphinx is too big a change.
To summarize why we're not going to move to Sphinx from MkDocs
Overview
Since the project is not yet deployed, non-developers can't see the swagger docs that are generated on the fly by the backend. We need to generate and add that to our documentation so that everyone can view them.
Action Items
After Merge
Resources/Instructions
More details
To clarify the issue description, the project does generate swagger docs using
drf-spectacular
, but it's on the fly only when the server is running. The packages in resources will generate a static version and put it inside the mkdocs site so it becomes part of the documentation separate from the running server.