DocCMiddleware enables quick and efficient hosting of DocC documentation with Vapor.
There are only a few quick steps required to host your DocC documentation with Vapor.
First, you need to generate a .doccarchive. You can do this directly from Xcode 13+, or you can leverage the swift-docc-plugin.
See distributing documentation to external developers for an overview.
Your
.doccarchivecan technically live anywhere within your Vapor workspace (it does not have to live in thePublic/directory), but the default location that the middleware looks for isDocs/in your workspace root.
Next, enable the middleware when your app is configuring, before you register routes. In a fresh Vapor project, this would take place in your configure.swift file.
To enable a single .doccarchive located at the root of your website, you just need to pass in the name of the archive.
app.middleware.use(DocCMiddleware(app: app, archive: "DocCMiddleware"))You can also pass in a hosting base path, which must match the value you used when generating documentation with the --hosting-base-path option.
app.middleware.use(DocCMiddleware(app: app, archive: .init(name: "DocCMiddleware", hostingBasePath: "DocCMiddleware")))If you did not pass the
--hosting-base-pathoption when generating documentation, this will not work!
If you're looking to host multiple .doccarchive files, you're in luck -- the middleware was designed to do just that.
app.middleware.use(DocCMiddleware(app: app, archives: ["Module1", "Module2", "Module3"]))Because multiple
.doccarchivefiles could not be located simultaneouly at the root, the above syntax assumes that each module uses its own name as a hosting base path.
And if you'd like to keep your docs in a different directory, such as Public/docs, that's no problem either.
app.middleware.use(DocCMiddleware(documentationDirectory: app.directory.publicDirectory.appending("docs"), archive: "DocCMiddleware"))Finally, run your website and navigate to the documentation.
If you did not use --hosting-base-path, it can be seen at localhost:8080 by default.
If you did use --hosting-base-path, then the value you passed in is the route to navigate to. (eg. --hosting-base-path MyModule corresponds to localhost:8080/MyModule.)
Routes will redirect to
<hosting-base-path>/documentation/MyModuleby default. This is built into the way the.doccarchiveworks and is not configurable at this time.
- Allow DocCMiddleware to serve up multiple
.doccarchivefiles. - Fix sidebar rendering.
- Allow the Middleware to serve static
.doccarchives. - Clean up, optimize, and test the middleware.
See it in action!
Discussions, issues, and pull requests are more than welcome!
This project is released under the MIT license. See LICENSE for details.
