From 817b47f0f7a87b72bf063cc0f5371627d518a7b2 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Fri, 23 Feb 2024 06:13:43 -0800 Subject: [PATCH] Refactor the index page to match the sidebar This is basically just pulling the main bits from the sidebar, and putting them in the front page. --- docs/user/index.rst | 133 ++++++++++++++++++++++++++------------------ 1 file changed, 78 insertions(+), 55 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index bdd7dda0edb..f190ae4cbae 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -125,19 +125,19 @@ by building, versioning, and hosting of your docs, automatically. Treating documentation like code keeps your team in the same tools, and your documentation up to date. -|:arrows_counterclockwise:| Up to date documentation +Up to date documentation Whenever you push code to Git, Read the Docs will automatically build your docs so your code and documentation are always up-to-date. Get started with our :doc:`tutorial `. -|:card_index_dividers:| Documentation for every version +Documentation for every version Read the Docs can host multiple versions of your docs. Keep your 1.0 and 2.0 documentation online, pulled directly from Git. Start hosting all your :doc:`versions `. -|:heartbeat:| Open source and user focused +Open source and user focused Our company is bootstrapped and 100% user-focused, so our product gets better for our users instead of our investors. |org_brand| hosts documentation for over 100,000 large @@ -152,89 +152,112 @@ We have a few places for you to get started: .. descriptions here are active -🚀 :doc:`/tutorial/index` +:doc:`/tutorial/index` Take the first practical steps with Read the Docs. -🚀 :doc:`/examples` +:doc:`/choosing-a-site` + Learn about the differences between |org_brand| and |com_brand|. + +:doc:`/examples` Start your journey with an example project to hit the ground running. -🚀 :doc:`All tutorials ` - Using documentation tools like Sphinx or MkDocs for the first time or importing an existing project? - We have the tutorials to get you started! +Project setup and configuration +------------------------------- -.. TODO: This above item needs its article to be finished in a separate PR -.. because of what seems to be a bug in Sphinx, we get two
items -.. if we put comments between items. -.. https://github.com/readthedocs/readthedocs.org/pull/10071 -.. This page isn't ready for front page treatment -.. doc:`Why use a dedicated documentation platform? ` -.. An introduction to some of the most important reasons for using a *Documentation CI* and build *docs as code*. +Start with the basics of setting up your project: +:doc:`/config-file/index` + Learn how to configure your project with a ``.readthedocs.yaml`` file. -Explanation ------------ +:doc:`/guides/reproducible-builds` + Learn how to make your builds reproducible. -Get a high-level overview of our platform: +Build process +------------- -.. Descriptions here are focused on learning +Build your documentation with ease: -.. TODO: This next item needs its article to be finished in a separate PR -.. https://github.com/readthedocs/readthedocs.org/pull/10071 +:doc:`/builds` + Overview of how documentation builds happen. -💡 :doc:`Continuous Documentation ` - Discover the advantages of having your documentation continuously deployed. +:doc:`/pull-requests` + Setup pull request builds and enjoy previews of each commit. -💡 :doc:`/choosing-a-site` - Learn about the differences between |org_brand| and |com_brand|. +Hosting documentation +--------------------- + +Learn more about our hosting features: -💡 :doc:`/explanation/advanced` - Get familiar with some of the more advanced topics of building and deploying documentation with Read the Docs. +:doc:`/versions` + Host multiple versions of your documentation. -💡 :doc:`All explanation articles ` - Browse all our explanation articles. +:doc:`/subprojects` + Host multiple projects under a single domain. +:doc:`/localization` + Host your documentation in multiple languages. + +:doc:`/versioning-schemes` + Learn about different versioning schemes. + +:doc:`/custom-domains` + Host your documentation on your own domain. + +Maintaining projects +-------------------- + +Keep your documentation up to date: + +:doc:`/user-defined-redirects` + Redirect your old URLs to new ones. + +:doc:`/reference/analytics` + Learn more about how users are interacting with your documentation. + +:doc:`/security-log` + Keep track of security events in your project. + +Business features +----------------- + +Features for organizations and businesses: + +:doc:`/commercial/index` + Learn more about our commercial features. + +:doc:`/commercial/organizations` + Learn how to manage your organization on Read the Docs. + +:doc:`/commercial/single-sign-on` + Learn how to use single sign-on with Read the Docs. How-to guides ------------- -Need to get something specific done? -These guides provide step-by-step instructions in key areas to get you up to speed faster: - -.. Descriptions here are active, learn, setup, etc. -.. The chosen sample of how-tos is intended reflect to width of the how-to section -.. i.e. NOT only what is most popular or easiest for beginners. +Step-by-step guides for common tasks: -🪄 :doc:`/guides/pull-requests` +:doc:`/guides/pull-requests` Setup pull request builds and enjoy previews of each commit. -🪄 :doc:`/analytics` +:doc:`/analytics` Learn more about how users are interacting with your documentation. -🪄 :doc:`/guides/cross-referencing-with-sphinx` +:doc:`/guides/cross-referencing-with-sphinx` Learn how to use cross-references in a Sphinx project. -🪄 :doc:`All how-to guides ` +:doc:`All how-to guides ` Browser the entire catalog for many more how-to guides. Reference --------- -Need to know how something works? -Here are a few of the most important reference docs: +More detailed information about Read the Docs: -.. Descriptions here sound like reference - -📚 :doc:`/reference/features` - Overview of all the main features of Read the Docs. - -📚 :doc:`/config-file/v2` - Information for our configuration file: ``.readthedocs.yaml``. - -📚 :doc:`/builds` - Overview of how documentation builds happen. +:doc:`/api/index` + Automate your documentation with our API and save yourself some work. -📚 :doc:`/build-customization` - Information on how to add your own build logic or replace default build steps. +:doc:`/changelog` + See what's new in Read the Docs. -📚 :doc:`/api/index` - Automate your documentation with our API and save yourself some work. +:doc:`/about/index` + Learn more about Read the Docs and our company.