0

I am leaving my internship currently and I'm in the process of writing documentation for the summer intern that is taking over after I graduate. I have written all of my docs in Markdown using MkDocs and I'm ready to deploy them. My docs use the Read the Docs theme that ships with MkDocs and I was hoping to have them hosted on RTD. However, the code for my docs is hosted in a private repo that belongs to my company's GitHub organization. I'm running into problems setting them up with RTD since I don't personally own the repo. Do any of you have any experience doing this? I've looked at the MkDocs 'Deploying your docs', but all of the hyperlinks are out of date and the guide mostly covers linking public repos.

Also -- I'm not married to RTD, it's just the MkDocs theme I used in my docs so if any of you have other suggestions, fire away!

Justin Dunlap
  • 109
  • 1
  • 3
  • 12

2 Answers2

0

RTD seems to have moved their documentation to https://docs.readthedocs.io/en/latest/. RTD's documentation specific to MkDocs is at https://docs.readthedocs.io/en/latest/intro/getting-started-with-mkdocs.html, however, that doesn't offer any instruction on how to deploy your MkDocs based site.

As it happens, the process for deploying to RTD is the same regardless of which of the supported static site generators you use (Sphinx or MkDocs) and is documented at https://docs.readthedocs.io/en/latest/intro/import-guide.html:

To import a public documentation repository, visit your Read the Docs dashboard and click Import. For private repositories, use the Read the Docs commercial solution.

If you have connected your Read the Docs account to GitHub, Bitbucket, or GitLab, you will see a list of your repositories that we are able to import. To import one of these projects, just click the import icon next to the repository you’d like to import. This will bring up a form that is already filled with your project’s information. Feel free to edit any of these properties, and then click Next to build your documentation.

Note that if you do not have (or want to have) your GitHub account connected with your RTD account, then you will need to manually import your repo, which is documented here. The documentation continues:

Within a few seconds of completing the import process, your code will automatically be fetched from your public repository, and the documentation will be built. Check out our Build Process page to learn more about how Read the Docs builds your docs, and to troubleshoot any issues that arise.

Some documentation projects require additional configuration to build such as specifying a certain version of Python or installing additional dependencies. You can configure these settings in a readthedocs.yml file. See our Configuration File docs for more details.

Last I checked, RTD was not using the most recent release of MkDocs by default, so you may want to make use of the readthedocs.yml file to specify the MkDocs version you have written your docs against as well as any third party plugins, themes, and/or Markdown Extensions you are using.

Waylan
  • 37,164
  • 12
  • 83
  • 109
0

You can have a look at V2 Documentation of ReadTheDocs

You will need 2 configuration files:

  1. mkdocs.yml
  2. .readthedocs.yml

both of them should be in the root of your project/repository

.readthedocs.yml should look like this (if you are not using any additional plugins).

# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Build documentation with MkDocs
#mkdocs:
#  configuration: mkdocs.yml
mkdocs:
  configuration: mkdocs.yml
  fail_on_warning: false

# Optionally build your docs in additional formats such as PDF and ePub
formats: all

Also make sure to change your Documentation Option to MKdocs on your readthedocs dashboard (Under Project > Admin > Advanced Settings)

Bhupesh Varshney
  • 1,522
  • 14
  • 19