Fix documentation generation #416
Conversation
| --github_url https://github.com/mongodb/mongo-swift-driver | ||
| --theme fullwidth | ||
| --documentation "Guides/*.md" | ||
| --github-file-prefix https://github.com/mongodb/mongo-swift-driver/tree/v${version} |
There was a problem hiding this comment.
this makes it so, if someone clicks one of the "view on github" links in the docs, it will take them to the place the code was at the time of the tag, rather than on master.
docs/index.html
Outdated
| </body> | ||
| </div> | ||
| </html> | ||
| <html><head><meta http-equiv="refresh" content="0; url=mongoswift/index.html" /></head></html> |
There was a problem hiding this comment.
copied from NIO. this makes it so if you go to the main documentation URL it forwards you to the MongoSwift docs main page (which has the README listing the modules).
patrickfreed
left a comment
patrickfreed
left a comment
There was a problem hiding this comment.
I only have a Linux machine with me right now, so I can't verify what everything looks like. That said, it all seems good to me besides one small typo in the development guide.
Guides/Development.md
Outdated
| Our documentation site is automatically generated from the source code using [Jazzy](https://github.com/realm/jazzy#installation). We regenerate it via our release script each time we release a new version of the driver. | ||
|
|
||
| If you'd like to preview how new documentation you've written will look when published, you can regenerate it by running `make documentation` and then inspecting the generated HTML files in `/docs`. | ||
| If you'd like to preview how new documentation you've written will look when published, you can regenerate it by running `.etc/generate-docs.sh` and then inspecting the generated HTML files in `/docs`. |
There was a problem hiding this comment.
typo: should be ./etc/generate-docs.sh
There was a problem hiding this comment.
I think you forgot to push the commit
kmahar
left a comment
kmahar
left a comment
There was a problem hiding this comment.
oh duh, I even saw you pack that laptop lol. trying to upload a zip file of the docs here and failing so I'll slack to you...
Guides/Development.md
Outdated
| Our documentation site is automatically generated from the source code using [Jazzy](https://github.com/realm/jazzy#installation). We regenerate it via our release script each time we release a new version of the driver. | ||
|
|
||
| If you'd like to preview how new documentation you've written will look when published, you can regenerate it by running `make documentation` and then inspecting the generated HTML files in `/docs`. | ||
| If you'd like to preview how new documentation you've written will look when published, you can regenerate it by running `.etc/generate-docs.sh` and then inspecting the generated HTML files in `/docs`. |
patrickfreed
left a comment
patrickfreed
left a comment
There was a problem hiding this comment.
the rendered documentation looked good, but since Linux filesystems are case-sensitive, I needed to change the mongoswift/index.html to MongoSwift/index.html to get it to work.
Guides/Development.md
Outdated
| Our documentation site is automatically generated from the source code using [Jazzy](https://github.com/realm/jazzy#installation). We regenerate it via our release script each time we release a new version of the driver. | ||
|
|
||
| If you'd like to preview how new documentation you've written will look when published, you can regenerate it by running `make documentation` and then inspecting the generated HTML files in `/docs`. | ||
| If you'd like to preview how new documentation you've written will look when published, you can regenerate it by running `.etc/generate-docs.sh` and then inspecting the generated HTML files in `/docs`. |
There was a problem hiding this comment.
I think you forgot to push the commit
|
pushed the commit from before, and also updated the path in |
docs/README.md
Outdated
|
|
||
| The MongoDB Swift driver contains two modules: | ||
|
|
||
| - [MongoSwift](../mongoswift/index.html), containing an asynchronous API and a BSON library |
There was a problem hiding this comment.
Oh I just realized these may need to be updated too. Otherwise lgtm
This adds a new script which handles generating documentation for both of our modules along with a pretty bare bones index page containing links to both.
It is very likely that this script does not work on Linux. A lot of the extra stuff in the SwiftNIO script is for that. But I don't want to hold up the release on getting the script to work there so I've left it out for now.
FYI: A follow up commit will be needed that cleans up everything in the
docs/directory besides the newREADME.mdand the editedindex.html, but I figured I would just merge that in directly after this, rather than cluttering up the PR.If you want to check out how all this looks locally I would suggest doing that deletion manually and then running the script.