Details

    • Type: Task
    • Status: Open
    • Priority: Medium
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: dcos-e2e
    • Labels:

      Description

      We use Read The Docs to build and host documentation for DC/OS E2E.

      We use Travis CI to run CI, including a check that the documentation builds.

      It is possible that documentation will build on Travis CI and it will not build on Read The Docs.
      For example, if the documentation building requires Docker (hint: it once did!).
      This means that we can make changes to master and later find that the docs fail.

      Another possibility is that the docs build with issues because of Sphinx warnings.
      Sometimes these warnings tell us that there will be malformed documentation.
      Ideally we would set -W on ReadTheDocs, but this is not yet possible:
      (GitHub issue here).
      We'd like to see that documentation will build fully before merging a PR.

      There is currently no way to trigger RTD builds for PRs (see GitHub issue here).

      I think that the solution is to use a Docker image to simulate RTD.
      A start of this is below.

      docker run -it readthedocs/build:latest bash
      
      mkdir -p /home/docs/checkouts/readthedocs.org/user_builds/dcos-e2e-cli/checkouts/delete-docs && \
      cd /home/docs/checkouts/readthedocs.org/user_builds/dcos-e2e-cli/checkouts/delete-docs && \
      git clone https://github.com/dcos/dcos-e2e . && \
      git checkout --force origin/delete-docs && \
      git clean -d -f -f && \
      git branch -r && \
      python3.5 -mvirtualenv --no-site-packages --no-download /home/docs/checkouts/readthedocs.org/user_builds/dcos-e2e-cli/envs/delete-docs && \
      python /home/docs/checkouts/readthedocs.org/user_builds/dcos-e2e-cli/envs/delete-docs/bin/pip install --upgrade --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/dcos-e2e-cli/.cache/pip Pygments==2.2.0 "setuptools<40" docutils==0.13.1 mock==1.0.1 pillow==2.6.1 "alabaster>=0.7,<0.8,!=0.7.5" commonmark==0.5.4 recommonmark==0.4.0 "sphinx<1.8" "sphinx-rtd-theme<0.5" "readthedocs-sphinx-ext<0.6" && \
      python /home/docs/checkouts/readthedocs.org/user_builds/dcos-e2e-cli/envs/delete-docs/bin/pip install --exists-action=w --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/dcos-e2e-cli/.cache/pip -r /home/docs/checkouts/readthedocs.org/user_builds/dcos-e2e-cli/checkouts/delete-docs/requirements.txt && \
      python /home/docs/checkouts/readthedocs.org/user_builds/dcos-e2e-cli/envs/delete-docs/bin/sphinx-build -T -b readthedocs -d _build/doctrees-readthedocs -D language=en . _build/html
      

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                Unassigned
                Reporter:
                adamdangoor Adam Dangoor (Inactive)
                Team:
                Mesosphere
                Watchers:
                Adam Dangoor (Inactive)
              • Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated: