Skip to content

Add basic landing page for any tool #337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 11, 2024
Merged

Add basic landing page for any tool #337

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aea33af
Add basic landing page for any tool
ericholscher Nov 21, 2024
4f25cbf
Apply suggestions from code review
ericholscher Dec 2, 2024
89c1f09
Other cleanup
ericholscher Dec 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 117 additions & 0 deletions content/includes/try-it-out-custom.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
<div class="ui container">
<div class="ui horizontal divider">Try it out</div>
</div>

<section id="try-it-out">
<div class="ui padded container">
<h2 class="ui huge center aligned header">
Upgrade your documentation with Read the Docs
</h2>

<div class="ui very padded centered grid">

<div class="ten wide computer sixteen wide tablet sixteen wide mobile column">
<div class="ui large left aligned basic vertical segment">

{# Stylized code blocks #}
{% call technical.code_block(title="<code>.readthedocs.yaml</code>", 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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is probably a case for using build.jobs.build.html

Copy link
Member Author

@ericholscher ericholscher Dec 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That doesn't currently work for non-Sphinx/Mkdocs currently (readthedocs/readthedocs.org#11810), and I think the goal of this page is to promote custom commands, so I think build.commands is fine for now.

# Python
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indentation is too far over here

# 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/
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should use the JS example over the Sphinx example, an unsupported tool would be even better to illustrate.


```
{% endmarkdown %}
{% endcall %}
</div>
</div>

<div class="middle aligned left aligned six wide computer twelve wide tablet sixteen wide mobile column">
<div class="ui padded basic segment">
<div class="ui relaxed list">

{%- set header_1 = "Create an account" %}
{%- set icon_1 = "fa-square-1" -%}
<span class="ui small teal header item">
<i class="fad {{ icon_1 }} secondary big icon"></i>
<span class="content">
{{ header_1 }}
<span class="sub header">
<a data-analytics="signup-modal"
onclick="jQuery('#signup-modal').modal('show');">
Sign up
</a>
with GitHub or your email.
</span>
</span>
</span>

{%- set header_2 = "Import your project" %}
{%- set icon_2 = "fa-square-2" -%}
<span class="ui small header item">
<i class="fad {{ icon_2 }} secondary big icon"></i>
<span class="content">
{{ header_2 }}
<span class="sub header">Select your existing Git repositories with a 1-click interface.</span>
</span>
</span>

{%- set header_3 = "Add YAML config" %}
{%- set icon_3 = "fa-square-3" -%}
<span class="ui small header item">
<i class="fad {{ icon_3 }} secondary big icon"></i>
<span class="content">
{{ header_3 }}
<span class="sub header">Copy this example, it probably does what you want 😉</span>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given our generic project example, I wouldn't suggest users copy this.

</span>
</span>

{%- set header_4 = "Your docs build on every commit" %}
{%- set icon_4 = "fa-square-4" -%}
<span class="ui small header item">
<i class="fad {{ icon_4 }} secondary big icon"></i>
<span class="content">
{{ header_4 }}
<span class="sub header">Like magic.</span>
</span>
</span>
</div>
</div>
</div>

</div>
</div>
</section>
124 changes: 124 additions & 0 deletions content/pages/custom.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/
#}

<html>
<head>
<title>Host Any Documentation Tool</title>
<meta name="template" content="page" />
<meta name="slug" content="tools/custom" />
<meta name="status" content="hidden" />
<meta name="description" content="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." />
</head>
<body>

{% import "partials/basic.html" as basic %}
{% import "partials/marketing.html" as marketing %}
{% import "partials/technical.html" as technical %}
{% import "partials/homepage.html" as homepage %}

<section>
{% 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")
%}
<p>
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.
</p>

<p class="ui basic padded vertical segment">
<a class="ui large teal stackable button"
data-analytics="signup-modal"
onclick="jQuery('#signup-modal').modal('show');">
<i class="fad fa-play icon"></i>
Create an account
</a>
<a href="https://docs.readthedocs.io/en/stable/build-customization.html#override-the-build-process" class="ui large stackable button">
Learn more
</a>
</p>
{% endcall %}
</section>

<section id="features">
{% 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 <strong>have confidence in changes</strong> 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 <strong>never lose documentation again</strong>.
{% 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.
<strong>Flexibility to support any tool</strong>.
{% endmarkdown %}
{% endcall %}

{% endcall %}
</section>

{# Try it out code block #}
{% include "includes/try-it-out-custom.html" %}

{% block homepage_bottom_callout %}
<section>
<div class="ui very padded container">
<div class="ui grid center aligned">

<div class="row">
<div class="column twelve wide computer sixteen wide tablet">

<div class="ui basic vertical huge segment">
<p>
<b>Get started with any documentation tool today.</b>
</p>

<p>
<a class="ui large teal stackable button"
data-analytics="signup-modal"
onclick="jQuery('#signup-modal').modal('show');">
<i class="fad fa-play icon"></i>
Create an account
</a>
</p>
</div>

</div>
</div>

</div>
</div>
</section>
{% endblock homepage_bottom_callout %}

</body>
</html>
1 change: 1 addition & 0 deletions readthedocs_theme/templates/includes/topnav.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@
<a class="item" href="{{ SITEURL }}/tools/sphinx">Sphinx</a>
<a class="item" href="{{ SITEURL }}/tools/mkdocs">Mkdocs</a>
<a class="item" href="{{ SITEURL }}/tools/jupyter-book">Jupyter Book</a>
<a class="item" href="{{ SITEURL }}/tools/custom">Any Tool</a>
</div>
</div>
{% endif %}
Expand Down
Loading