Document deploying

[d0ugal]

This should be a fairly short document, but it is worth covering the options. Should cover:

• read the docs
• GitHub pages
• self hosting
• pypi?

[waylan]

I agree with all of these except maybe Read the Docs. They have their own tool and yours would add nothing except convenience.

Not sure about self hosting. While certainly nice-to-have, the possible options out there leave it pretty broad. Basic FTP upload would be simple enough. Not sure if you had anything else in mind.

[d0ugal]

I see this page as collecting the most likely options for our users. So it might be as simple as pointing users to the relevant ReadTheDocs documentation and letting them know they support MkDocs. For self hosting, I probably just want to state how self hosting is trivial as everything is static.

It may also be worth mentioning S3 as an option.

People sometimes come and ask about these things in IRC, so I mostly want this as a place to link to when doing support.

[waylan]

Here are some notes on PyPI for future reference:

This could be tricky to do as a subcommand of mkdocs. Meta-data regarding the PyPI repository is needed to do the upload to PyPI (primarily which repo and the associated username and password). Sphinx-PyPI-upload works because it registers itself as a subcommand with setuptools (it is run as python setup.py upload_sphinx). Therefore, it has access to the meta-data from within the script. Twine is able to interact with PyPI without being a setuptools subcommand, but is pulls the metadata from the build files that it is uploading. In the case of documentation (which twine does not handle), there is no PyPI based meta-data with the build and we don't want to force a distribution to be built before uploading documentation. Is there a setuptools command that outputs meta-data only?

Interestingly, I see no reason why Sphinx-PyPI-upload couldn't work out-of-the-box. You can point it at a specific directory of already built docs to zip and upload. Technically, that dir doesn't need to have been created by Sphinx. In fact, Sphinx-PyPI-upload always assumes the docs have already been built and has no actual dependency on Sphinx. At worst a quick read of the source suggests that it might assume that the docs are contained within a subdir (named html) of the given build dir (I have not tested this).

At most, I think a mkdocs deploy script for PyPI would pull the build dir from the mkdocs config, and call Sphinx-PyPI-upload passing it the build dir. Although, as Sphinx-PyPI-upload can be configured via setup.cfg, that is not really necessary -- it just ensures the two configs don't get out-of-sync.

[d0ugal]

@waylan Neat! Thanks for doing this research - sounds like it is a bit more involved than I realised.

[waylan]

I think my preferred scenario would be for Twine to add an upload_docs command which would basically be a more generic fork of Sphinx-PyPI-upload. Then you could just tell people to use Twine for all PyPI interaction. The next best thing would be a standalone generic fork of Sphinx-PyPI-upload (maybe "PyPI-Upload-Docs"??). Actually, Twine allows for subcommands to be registered as entry_points, so the standalone script could work at a Twine extension. Then you could still tell people to use Twine (with the necessary extension). The trick with the standalone script is getting the meta-data. When I get some free time (it may be awhile) I'll play around with this and see what I can come up with (deploying to PyPI is what I need).

[d0ugal]

I found this after a quick search, looks like they don't want to add it to Twine. pypa/twine#12

A Twine extension sounds like a nice way to go with this, I'll help if I can and otherwise I'd certainly document it!

[waylan]

Not sure how I missed this, but setuptools has an upload_docs command which appears to have started out as Sphinx-PyPI-upload. However, it does not assume a Sphinx build dir (it doesn't append html/ to the provided build dir. The upload_docs command offers everything needed after a build.

mkdocs build --clean
python setup.py upload_docs --upload-dir=site

As per the docs, a setup.cfg can be used to configure the upload-dir so it does not need to be explicitly defined every time. Note that if --upload-dir is not defined (either on the command line or in the config), it tries to build the docs first and the build assumes Sphinx.

[d0ugal]

Fixed by #566

[waylan]

Did you intend to close this?

[d0ugal]

Yup, thanks.