title: How do I correctly start using .readthedocs.yml
body: <p>I have a basic ReadTheDocs repository. As per the advice of the build page, I sought to use a <code>.readthedocs.yml</code> to configure it:</p>
  
  <blockquote>
    <p><strong>Configure your documentation builds!</strong> Adding a .readthedocs.yml file to your project is the recommended way to configure your documentation builds. You can declare dependencies, set up submodules, and many other great features.</p>
  </blockquote>
  
  <p>I added a basic <code>.readthedocs.yml</code>:</p>
  
  <pre><code>version: 2
  
  sphinx:
    builder: dirhtml
    fail_on_warning: true
  </code></pre>
  
  <p>and got a build failure:</p>
  
  <blockquote>
    <p>Problem in your project's configuration. Invalid "sphinx.builder": .readthedocs.yml: Your project is configured as "Sphinx Html" in your admin dashboard, but your "sphinx.builder" key does not match.</p>
  </blockquote>
  
  <p>This was surprising as it seemed contrary to the guidance in the admin dashboard at <a href="https://readthedocs.org/dashboard/PROJECTNAME/advanced/" rel="nofollow noreferrer">https://readthedocs.org/dashboard/PROJECTNAME/advanced/</a> which led me to assume that I could set whatever I liked in the admin dashboard, but it would be overridden by my <code>.readthedocs.yml</code> (which is the behaviour I expected and wanted):</p>
  
  <blockquote>
    <p>These settings can be configured using a configuration file. That's the recommended way to set up your project. Settings in the configuration file override the settings listed here.</p>
  </blockquote>
  
  <p>I updated the setting in the admin dashboard to match the <code>.readthedocs.yml</code> and then got a build error:</p>
  
  <pre><code>Sphinx error:
  master file /home/docs/checkouts/readthedocs.org/user_builds/PROJECT_NAME/checkouts/latest/source/contents.rst not found
  </code></pre>
  
  <p>which looks like <a href="https://github.com/readthedocs/readthedocs.org/issues/2569" rel="nofollow noreferrer">https://github.com/readthedocs/readthedocs.org/issues/2569</a> (RTD not finding Sphinx configuration) - but it's not clear why that's happening because prior to adding <code>.readthedocs.yml</code>, the project built just fine.</p>
  
  <p>I'm struggling to model what's actually going on here:</p>
  
  <ul>
  <li>The config file isn't acting as an "overlay" / "override" onto the web settings - as per the first error, some forms of disagreement are a build failure</li>
  <li>It's <em>almost</em> like if the config file exists, the web config is ignored - this would explain the <code>contents.rst</code> issue arising, but this isn't consistent with the first error</li>
  </ul>
  
  <p>Adding a <code>python.install</code> entry to <code>.readthedocs.yml</code> eventually got the site building, but it's still not clear to me if I'm generally doing the right thing, and/or how successful future config changes will be.</p>