CINXE.COM

<!DOCTYPE html> <html class="writer-html5" lang="en" data-content_root="./"> <head> <meta charset="utf-8" /> <meta name="readthedocs-addons-api-version" content="1"><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta property="og:title" content="Subprojects" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://docs.readthedocs.io/en/stable/subprojects.html" /> <meta property="og:site_name" content="Read the Docs Documentation" /> <meta property="og:description" content="In this article, you can learn more about how several documentation projects can be combined and presented to the reader on the same website. Read the Docs can be configured to make other projects available on the website of the main project as subprojects. This allows for documentation projects ..." /> <meta property="og:image" content="https://docs.readthedocs.io/en/latest/_static/img/logo-opengraph.png" /> <meta property="og:image:alt" content="Read the Docs Documentation" /> <meta name="description" content="In this article, you can learn more about how several documentation projects can be combined and presented to the reader on the same website. Read the Docs can be configured to make other projects available on the website of the main project as subprojects. This allows for documentation projects ..." /> <meta name="twitter:card" content="summary_large_image" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Subprojects — Read the Docs user documentation</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=80d5e7a1" /> <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" /> <link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="_static/sphinx-design.min.css?v=95c83b7e" /> <link rel="stylesheet" type="text/css" href="_static/css/custom.css?v=da32ccdd" /> <link rel="stylesheet" type="text/css" href="_static/css/sphinx_prompt_css.css?v=351d85e3" /> <link rel="canonical" href="https://docs.readthedocs.io/en/stable/subprojects.html" /> <script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/documentation_options.js?v=604cd17f"></script> <script src="_static/doctools.js?v=9bcbadda"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/clipboard.min.js?v=a7894cd8"></script> <script src="_static/copybutton.js?v=f281be69"></script> <script src="_static/design-tabs.js?v=f930bc37"></script> <script src="_static/js/expand_tabs.js?v=1e151f68"></script> <script src="_static/js/theme.js"></script> <script src="_static/js/versions.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Localization and Internationalization" href="localization.html" /> <link rel="prev" title="Versions" href="versions.html" /> <script defer data-domain="docs.readthedocs.io" src="https://plausible.io/js/script.js"></script> <script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="docs" /><meta name="readthedocs-version-slug" content="stable" /><meta name="readthedocs-resolver-filename" content="/subprojects.html" /><meta name="readthedocs-http-status" content="200" /></head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html"> <img src="_static/logo.svg" class="logo" alt="Logo"/> </a> <div class="switch-menus"> <div class="version-switch"></div> <div class="language-switch"></div> </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <p class="caption" role="heading"><span class="caption-text">Getting started</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Read the Docs tutorial</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/doctools.html">Supported tools</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/mkdocs.html">Material for MkDocs</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/sphinx.html">Sphinx</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/markdoc.html">Markdoc</a></li> <li class="toctree-l1"><a class="reference internal" href="intro/add-project.html">Adding a documentation project</a></li> <li class="toctree-l1"><a class="reference internal" href="examples.html">Example projects</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Project setup and configuration</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="config-file/index.html">Configuration file overview</a></li> <li class="toctree-l1"><a class="reference internal" href="config-file/v2.html">Configuration file reference</a></li> <li class="toctree-l1"><a class="reference internal" href="addons.html">Read the Docs Addons</a></li> <li class="toctree-l1"><a class="reference internal" href="automation-rules.html">Automation rules</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/reproducible-builds.html">How to create reproducible builds</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Build process</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="builds.html">Build process overview</a></li> <li class="toctree-l1"><a class="reference internal" href="build-customization.html">Build process customization</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/git-integration.html">Git integration (GitHub, GitLab, Bitbucket)</a></li> <li class="toctree-l1"><a class="reference internal" href="pull-requests.html">Pull request previews</a></li> <li class="toctree-l1"><a class="reference internal" href="build-notifications.html">Build failure notifications</a></li> <li class="toctree-l1"><a class="reference internal" href="environment-variables.html">Environment variable overview</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/environment-variables.html">Environment variable reference</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Hosting documentation</span></p> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="versions.html">Versions</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Subprojects</a><ul> <li class="toctree-l2"><a class="reference internal" href="#sharing-a-custom-domain">Sharing a custom domain</a></li> <li class="toctree-l2"><a class="reference internal" href="#using-aliases">Using aliases</a></li> <li class="toctree-l2"><a class="reference internal" href="#custom-domain-on-subprojects">Custom domain on subprojects</a></li> <li class="toctree-l2"><a class="reference internal" href="#separate-release-cycles">Separate release cycles</a></li> <li class="toctree-l2"><a class="reference internal" href="#search">Search</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="localization.html">Localization and Internationalization</a></li> <li class="toctree-l1"><a class="reference internal" href="versioning-schemes.html">URL versioning schemes</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-domains.html">Custom domains</a></li> <li class="toctree-l1"><a class="reference internal" href="doc-notifications.html">Documentation notifications</a></li> <li class="toctree-l1"><a class="reference internal" href="canonical-urls.html">Canonical URLs</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/cdn.html">Content Delivery Network (CDN) and caching</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/sitemaps.html">Sitemap support</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/404-not-found.html"><code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code> pages</a></li> <li class="toctree-l1"><a class="reference internal" href="reference/robots.html"><code class="docutils literal notranslate"><span class="pre">robots.txt</span></code> support</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Reading documentation</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="downloadable-documentation.html">Offline formats (PDF, ePub, HTML)</a></li> <li class="toctree-l1"><a class="reference internal" href="doc-diff.html">DocDiff</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/embedding-content.html">How to embed content from your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="server-side-search/index.html">Server side search</a></li> <li class="toctree-l1"><a class="reference internal" href="server-side-search/syntax.html">Search query syntax</a></li> <li class="toctree-l1"><a class="reference internal" href="flyout-menu.html">Flyout menu</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Maintaining projects</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="user-defined-redirects.html">Redirects</a></li> <li class="toctree-l1"><a class="reference internal" href="traffic-analytics.html">Traffic analytics</a></li> <li class="toctree-l1"><a class="reference internal" href="search-analytics.html">Search analytics</a></li> <li class="toctree-l1"><a class="reference internal" href="security-log.html">Security logs</a></li> <li class="toctree-l1"><a class="reference internal" href="badges.html">Status badges</a></li> <li class="toctree-l1"><a class="reference internal" href="explanation/documentation-structure.html">How to structure your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/best-practice/links.html">Best practices for linking to your documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="security-implications.html">Security considerations for documentation pages</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Business features</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="commercial/index.html">Business hosting</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/organizations.html">Organizations</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/single-sign-on.html">Single Sign-On (SSO)</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/sharing.html">Sharing private documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/subscriptions.html">How to manage your subscription</a></li> <li class="toctree-l1"><a class="reference internal" href="commercial/privacy-level.html">Privacy Levels</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">How-to guides</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="guides/setup/index.html">Project setup and configuration</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/build/index.html">Build process</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/maintenance/index.html">Upgrading and maintaining projects</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/content/index.html">Content, themes and SEO</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/access/index.html">Security and access</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/management/index.html">Account management</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/best-practice/index.html">Best practice</a></li> <li class="toctree-l1"><a class="reference internal" href="guides/troubleshooting/index.html">Troubleshooting problems</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Reference</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="api/index.html">Public REST API</a></li> <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently asked questions</a></li> <li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li> <li class="toctree-l1"><a class="reference internal" href="about/index.html">About Read the Docs</a></li> <li class="toctree-l1"><a class="reference external" href="https://dev.readthedocs.io">Developer Documentation</a></li> <li class="toctree-l1"><a class="reference external" href="https://about.readthedocs.com">Read the Docs website</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">Read the Docs user documentation</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item active">Subprojects</li> <li class="wy-breadcrumbs-aside"> <a href="https://github.com/readthedocs/readthedocs.org/blob/main/docs/user/subprojects.rst" class="fa fa-github"> Edit on GitHub</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="subprojects"> <h1>Subprojects<a class="headerlink" href="#subprojects" title="Link to this heading"></a></h1> <p>In this article, you can learn more about how several documentation projects can be combined and presented to the reader on the same website.</p> <p>Read the Docs can be configured to make other <em>projects</em> available on the website of the <em>main project</em> as <strong>subprojects</strong>. This allows for documentation projects to share a search index and a namespace or custom domain, but still be maintained independently.</p> <p>This is useful for:</p> <ul class="simple"> <li><p>Organizations that need all their projects visible in one documentation portal or landing page</p></li> <li><p>Projects that document and release several packages or extensions</p></li> <li><p>Organizations or projects that want to have a common search function for several sets of documentation</p></li> </ul> <p>For a main project <code class="docutils literal notranslate"><span class="pre">example-project</span></code>, a subproject <code class="docutils literal notranslate"><span class="pre">example-project-plugin</span></code> can be made available as follows:</p> <ul class="simple"> <li><p>Main project: <code class="docutils literal notranslate"><span class="pre">https://example-project.readthedocs.io/en/latest/</span></code></p></li> <li><p>Subproject: <code class="docutils literal notranslate"><span class="pre">https://example-project.readthedocs.io/projects/plugin/en/latest/</span></code></p></li> </ul> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt><a class="reference internal" href="guides/subprojects.html"><span class="doc">How to manage subprojects</span></a></dt><dd><p>Learn how to create and manage subprojects</p> </dd> <dt><a class="reference internal" href="guides/intersphinx.html"><span class="doc">How to link to other documentation projects with Intersphinx</span></a></dt><dd><p>Learn how to use references between different Sphinx projects, for instance between subprojects</p> </dd> </dl> </div> <section id="sharing-a-custom-domain"> <h2>Sharing a custom domain<a class="headerlink" href="#sharing-a-custom-domain" title="Link to this heading"></a></h2> <p>Projects and subprojects can be used to share a custom domain. To configure this, one project should be established as the main project and configured with a custom domain. Other projects are then added as subprojects to the main project.</p> <p>If the example project <code class="docutils literal notranslate"><span class="pre">example-project</span></code> was set up with a custom domain, <code class="docutils literal notranslate"><span class="pre">docs.example.com</span></code>, the URLs for projects <code class="docutils literal notranslate"><span class="pre">example-project</span></code> and <code class="docutils literal notranslate"><span class="pre">example-project-plugin</span></code> with alias <code class="docutils literal notranslate"><span class="pre">plugin</span></code> would respectively be at:</p> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">example-project</span></code>: <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/en/latest/</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">example-project-plugin</span></code>: <code class="docutils literal notranslate"><span class="pre">https://docs.example.com/projects/plugin/en/latest/</span></code></p></li> </ul> </section> <section id="using-aliases"> <h2>Using aliases<a class="headerlink" href="#using-aliases" title="Link to this heading"></a></h2> <p>Adding an alias for the subproject allows you to override the URL that is used to access it, giving more control over how you want to structure your projects. You can choose an alias for the subproject when it is created.</p> <p>You can set your subproject’s project name and <a class="reference internal" href="glossary.html#term-slug"><span class="xref std std-term">slug</span></a> however you want, but we suggest prefixing it with the name of the main project.</p> <p>Typically, a subproject is created with a <code class="docutils literal notranslate"><span class="pre"><mainproject>-</span></code> prefix, for instance if the main project is called <code class="docutils literal notranslate"><span class="pre">example-project</span></code> and the subproject is called <code class="docutils literal notranslate"><span class="pre">plugin</span></code>, then the subproject’s Read the Docs project <a class="reference internal" href="glossary.html#term-slug"><span class="xref std std-term">slug</span></a> will be <code class="docutils literal notranslate"><span class="pre">example-project-plugin</span></code>. When adding the subproject, the alias is set to <code class="docutils literal notranslate"><span class="pre">plugin</span></code> and the project’s URL becomes <code class="docutils literal notranslate"><span class="pre">example-project.readthedocs.io/projects/plugin</span></code>.</p> <p>When you add a subproject, the subproject will not be directly available anymore from its own domain. For instance, <code class="docutils literal notranslate"><span class="pre">example-project-plugin.readthedocs.io/</span></code> will redirect to <code class="docutils literal notranslate"><span class="pre">example-project.readthedocs.io/projects/plugin</span></code>.</p> </section> <section id="custom-domain-on-subprojects"> <h2>Custom domain on subprojects<a class="headerlink" href="#custom-domain-on-subprojects" title="Link to this heading"></a></h2> <p>Adding a custom domain to a subproject is not allowed, since your documentation will always be served from the domain of the parent project.</p> </section> <section id="separate-release-cycles"> <h2>Separate release cycles<a class="headerlink" href="#separate-release-cycles" title="Link to this heading"></a></h2> <p>By using subprojects, you can present the documentation of several projects even though they have separate release cycles.</p> <p>Your main project may have its own versions and releases, while all of its subprojects maintain their own individual versions and releases. We recommend that documentation follows the release cycle of whatever it is documenting, meaning that your subprojects should be free to follow their own release cycle.</p> <p>This is solved by having an individual <a class="reference internal" href="glossary.html#term-flyout-menu"><span class="xref std std-term">flyout menu</span></a> active for the project that’s viewed. When the user navigates to a subproject, they are presented with a flyout menu matching the subproject’s versions and <a class="reference internal" href="downloadable-documentation.html"><span class="doc">Offline formats (PDF, ePub, HTML)</span></a>.</p> </section> <section id="search"> <h2>Search<a class="headerlink" href="#search" title="Link to this heading"></a></h2> <p>Search on the parent project will include results from its subprojects. If you search on the <code class="docutils literal notranslate"><span class="pre">v1</span></code> version of the parent project, results from the <code class="docutils literal notranslate"><span class="pre">v1</span></code> version of its subprojects will be included, or from the default version for subprojects that don’t have a <code class="docutils literal notranslate"><span class="pre">v1</span></code> version.</p> <p>This is currently the only way to share search results between projects, we do not yet support sharing search results between sibling subprojects or arbitrary projects.</p> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="versions.html" class="btn btn-neutral float-left" title="Versions" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="localization.html" class="btn btn-neutral float-right" title="Localization and Internationalization" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> <div role="contentinfo"> <p>© Copyright Read the Docs, Inc & contributors.</p> </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>