From aea33af267287566301a36f2c5605b8b9b1b3113 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 20 Nov 2024 16:37:23 -0800 Subject: [PATCH 1/3] Add basic landing page for any tool This is just a starting point with a generic config. Fixes https://github.com/readthedocs/website/issues/301 --- content/includes/try-it-out-custom.html | 117 +++++++++++++++++ content/pages/custom.html | 124 ++++++++++++++++++ .../templates/includes/topnav.html | 1 + 3 files changed, 242 insertions(+) create mode 100644 content/includes/try-it-out-custom.html create mode 100644 content/pages/custom.html diff --git a/content/includes/try-it-out-custom.html b/content/includes/try-it-out-custom.html new file mode 100644 index 00000000..060e58eb --- /dev/null +++ b/content/includes/try-it-out-custom.html @@ -0,0 +1,117 @@ +
+
Try it out
+
+ +
+
+

+ Upgrade your documentation with Read the Docs +

+ +
+ +
+
+ + {# Stylized code blocks #} + {% call technical.code_block(title=".readthedocs.yaml", icon="fa-file") %} + {% markdown %} + + ```yaml + # Read the Docs configuration file for Sphinx projects + # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + + # Required + version: 2 + + # Set the OS, Python version and other tools you might need + build: + os: ubuntu-24.04 + tools: + python: "3.12" + nodejs: "20" + # You can also specify other tool versions: + # rust: "1.70" + # golang: "1.20" + + commands: + # Python + # Install dependencies + - pip install -r docs/requirements.txt + # Build the site + - make html + # Copy generated files into Read the Docs directory + - mkdir --parents $READTHEDOCS_OUTPUT/html/ + - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ + + # Node + # Install dependencies + - cd docs/ && npm install + # Build the site + - cd docs/ && npm run build + # Copy generated files into Read the Docs directory + - mkdir --parents $READTHEDOCS_OUTPUT/html/ + - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ + + ``` + {% endmarkdown %} + {% endcall %} +
+
+ +
+
+
+ + {%- set header_1 = "Create an account" %} + {%- set icon_1 = "fa-square-1" -%} + + + + {{ header_1 }} + + + Sign up + + with GitHub or your email. + + + + + {%- set header_2 = "Import your project" %} + {%- set icon_2 = "fa-square-2" -%} + + + + {{ header_2 }} + Select your existing Git repositories with a 1-click interface. + + + + {%- set header_3 = "Add YAML config" %} + {%- set icon_3 = "fa-square-3" -%} + + + + {{ header_3 }} + Copy this example, it probably does what you want 😉 + + + + {%- set header_4 = "Your docs build on every commit" %} + {%- set icon_4 = "fa-square-4" -%} + + + + {{ header_4 }} + Like magic. + + +
+
+
+ +
+
+
diff --git a/content/pages/custom.html b/content/pages/custom.html new file mode 100644 index 00000000..5402ad00 --- /dev/null +++ b/content/pages/custom.html @@ -0,0 +1,124 @@ +{# + The goal of this page is to highlight the flexibility of our platform in supporting any documentation tool, + with full customization of the build commands you can run. +#} + +{# + View this page at http://localhost:8080/tools/custom/ +#} + + + + Host Any Documentation Tool + + + + + + + +{% import "partials/basic.html" as basic %} +{% import "partials/marketing.html" as marketing %} +{% import "partials/technical.html" as technical %} +{% import "partials/homepage.html" as homepage %} + +
+ {% call basic.header_image( + header="Deploy With Any Tool", + image="/images/homepage.png", + image_alt="Examples of Read the Docs hosted documentation", + vertical_align="middle") + %} +

+ Read the Docs supports any documentation tool with full customization of the build commands you can run. + Enjoy powerful features such as search-as-you-type, previews from Git, and much more. +

+ +

+ + + Create an account + + + Learn more + +

+ {% endcall %} +
+ +
+ {% call marketing.highlight_list() %} + + {% call marketing.highlight_item( + icon="olive fa-people-arrows", + icon_style="--fa-secondary-color: violet; --fa-secondary-opacity: 1;", + header="Collaborate with deploy previews", + color="violet") %} + {% markdown %} + Receive feedback from your team, + and have confidence in changes before they go live. + {% endmarkdown %} + {% endcall %} + + {% call marketing.highlight_item( + icon="yellow fa-magnifying-glass", + icon_style="--fa-secondary-color: white; --fa-secondary-opacity: 1;", + header="Always find what you need", + color="violet") %} + {% markdown %} + Search across all your projects with our search-as-you-type interface, + and never lose documentation again. + {% endmarkdown %} + {% endcall %} + + {% call marketing.highlight_item( + icon="fa-cogs", + header="Full customization of build commands", + color="violet") %} + {% markdown %} + Customize the build commands to suit your project's needs. + Flexibility to support any tool. + {% endmarkdown %} + {% endcall %} + + {% endcall %} +
+ +{# Try it out code block #} +{% include "includes/try-it-out-custom.html" %} + +{% block homepage_bottom_callout %} +
+
+
+ +
+
+ +
+

+ Get started with any documentation tool today. +

+ +

+ + + Create an account + +

+
+ +
+
+ +
+
+
+{% endblock homepage_bottom_callout %} + + + diff --git a/readthedocs_theme/templates/includes/topnav.html b/readthedocs_theme/templates/includes/topnav.html index 6c405912..c4b458a6 100644 --- a/readthedocs_theme/templates/includes/topnav.html +++ b/readthedocs_theme/templates/includes/topnav.html @@ -46,6 +46,7 @@ Sphinx Mkdocs Jupyter Book + Any Tool {% endif %} From 4f25cbfedffb5668f7286ccdd37e1bd8cfb65f3d Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Mon, 2 Dec 2024 14:21:47 -0800 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Anthony --- content/pages/custom.html | 8 ++++---- readthedocs_theme/templates/includes/topnav.html | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/content/pages/custom.html b/content/pages/custom.html index 5402ad00..f1829f73 100644 --- a/content/pages/custom.html +++ b/content/pages/custom.html @@ -9,11 +9,11 @@ - Host Any Documentation Tool + Host any documentation tool - + @@ -24,13 +24,13 @@
{% call basic.header_image( - header="Deploy With Any Tool", + header="Deploy with any tool", image="/images/homepage.png", image_alt="Examples of Read the Docs hosted documentation", vertical_align="middle") %}

- Read the Docs supports any documentation tool with full customization of the build commands you can run. + Read the Docs supports any documentation tool by allowing full control of the build commands your project runs. Enjoy powerful features such as search-as-you-type, previews from Git, and much more.

diff --git a/readthedocs_theme/templates/includes/topnav.html b/readthedocs_theme/templates/includes/topnav.html index c4b458a6..b9d9bcb8 100644 --- a/readthedocs_theme/templates/includes/topnav.html +++ b/readthedocs_theme/templates/includes/topnav.html @@ -46,7 +46,7 @@ Sphinx Mkdocs Jupyter Book - Any Tool + Other tools {% endif %} From 89c1f093ff9a98a2d4e586e7921dce8a9f72c8ac Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Mon, 2 Dec 2024 17:23:38 -0500 Subject: [PATCH 3/3] Other cleanup --- content/includes/try-it-out-custom.html | 27 +++++++++---------------- 1 file changed, 9 insertions(+), 18 deletions(-) diff --git a/content/includes/try-it-out-custom.html b/content/includes/try-it-out-custom.html index 060e58eb..b902faa2 100644 --- a/content/includes/try-it-out-custom.html +++ b/content/includes/try-it-out-custom.html @@ -34,24 +34,15 @@

# rust: "1.70" # golang: "1.20" + # Support any tool with custom build commands commands: - # Python - # Install dependencies - - pip install -r docs/requirements.txt - # Build the site - - make html - # Copy generated files into Read the Docs directory - - mkdir --parents $READTHEDOCS_OUTPUT/html/ - - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ - - # Node - # Install dependencies - - cd docs/ && npm install - # Build the site - - cd docs/ && npm run build - # Copy generated files into Read the Docs directory - - mkdir --parents $READTHEDOCS_OUTPUT/html/ - - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ + # Install dependencies + - cd docs/ && npm install + # Build the site + - cd docs/ && npm run build + # Copy generated files into Read the Docs directory + - mkdir --parents $READTHEDOCS_OUTPUT/html/ + - cp --recursive docs/build/* $READTHEDOCS_OUTPUT/html/ ``` {% endmarkdown %} @@ -95,7 +86,7 @@

{{ header_3 }} - Copy this example, it probably does what you want 😉 + Start with this example, and then adapt it.