Skip to content

Commit

Permalink
Add project: show more yaml examples (#368)
Browse files Browse the repository at this point in the history 
* Add project: show more `yaml` examples

I used tabs to show different examples of YAML files, as suggested in #184.
It looks great for an initial interactive approach.

I like the tabs over the dropdown because it gives the user a clear idea there
are more than Sphinx and MkDocs tools supported, which is a good marketing
strategy, in my opinion.

It also adds an "Others" option that's more generic and shows how to use
`build.commands` in a generic way: install dependencies, build, copy assets
under `$READTHDOCS_OUTPUT` directory.

* Update readthedocsext/theme/templates/projects/import_config.html

Co-authored-by: Anthony <aj@ohess.org>

* Update readthedocsext/theme/templates/projects/import_config.html

Co-authored-by: Anthony <aj@ohess.org>

* Combine Dropdown + Tabs

* Fix indentation

* More indentation

---------

Co-authored-by: Anthony <aj@ohess.org>
  • Loading branch information
@humitos @agjohnson
humitos and agjohnson authored Jun 10, 2024
1 parent 74ba2e5 commit 228f122
Showing 1 changed file with 217 additions and 27 deletions.
244 changes: 217 additions & 27 deletions readthedocsext/theme/templates/projects/import_config.html
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
{% extends "projects/import_base.html" %}
{% load i18n %}

{% block project_add_content_subheader %}
{% block project_add_subheader %}
{% trans "Add a configuration file to your project" %}
{% endblock project_add_content_subheader %}
{% endblock project_add_subheader %}

{% block project_add_content_classes %}ui fourteen wide tablet twelve wide computer column{% endblock %}

Expand All @@ -12,26 +12,20 @@
{% blocktrans trimmed %}
A <code>.readthedocs.yaml</code> configuration file is required at the root of your repository in order to build your documentation.
{% endblocktrans %}

<a href="https://docs.readthedocs.io/page/config-file/index.html" target="_blank">
{% trans "Learn how to add a configuration file to your project." %}
</a>
</div>

<div class="ui basic fitted right aligned segment">
<span>{% trans "Example configuration for:" %}</span>
<div class="ui inline dropdown" data-bind="semanticui: { dropdown: {}}">
<input type="hidden" name="tool" value="sphinx">
<span class="text">Sphinx</span>
<i class="dropdown icon"></i>
<div class="menu">
<div class="item" data-value="sphinx">Sphinx</div>

{% comment %}
Adding a second option here will require a bit of JS or FUI:
https://github.com/readthedocs/ext-theme/issues/184
{% endcomment %}

<div class="menu" data-bind="semanticui: { tabmenu: {}}">
<div class="item" data-tab="sphinx">Sphinx</div>
<div class="item" data-tab="mkdocs">MkDocs</div>
<div class="item" data-tab="pelican">Pelican</div>
<div class="item" data-tab="docusaurus">Docusaurus</div>
<div class="item" data-tab="jekyll">Jekyll</div>
<div class="item" data-tab="others">{% trans "Others" %}</div>
{# The `actionable` class here prevents the select from selecting the text #}
<a class="actionable item" href="https://docs.readthedocs.io/page/config-file/index.html#getting-started-with-a-template" target="_blank">
{% trans "See more examples" %}
Expand All @@ -40,15 +34,16 @@
</div>
</div>

<div class="ui mini padded inverted scrolling segment">
<div class="ui top attached label">
<code>.readthedocs.yaml</code>
</div>
<a class="ui top right attached icon label" href="#" data-clipboard-target="#project-create-sample-sphinx">
<i class="fas fa-copy icon"></i>
</a>
<code class="highlight">
<pre id="project-create-sample-sphinx">
<div class="ui bottom attached active tab" data-tab="sphinx">
<div class="ui mini padded inverted scrolling segment">
<div class="ui top attached label">
<code>.readthedocs.yaml</code>
</div>
<a class="ui top right attached icon label" href="#" data-clipboard-target="#project-create-sample-sphinx">
<i class="fas fa-copy icon"></i>
</a>
<code class="highlight">
<pre id="project-create-sample-sphinx">
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

Expand All @@ -59,7 +54,7 @@
build:
os: ubuntu-22.04
tools:
python: "3.11"
python: "3.12"
# You can also specify other tool versions:
# nodejs: "19"
# rust: "1.64"
Expand All @@ -80,8 +75,203 @@
# python:
# install:
# - requirements: docs/requirements.txt
</pre>
</code>
</pre>
</code>
</div>
</div>

<div class="ui bottom attached tab" data-tab="mkdocs">
<div class="ui mini padded inverted scrolling segment">
<div class="ui top attached label">
<code>.readthedocs.yaml</code>
</div>
<a class="ui top right attached icon label" href="#" data-clipboard-target="#project-create-sample-mkdocs">
<i class="fas fa-copy icon"></i>
</a>
<code class="highlight">
<pre id="project-create-sample-mkdocs">
# Read the Docs configuration file
# 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-22.04
tools:
python: "3.12"
# You can also specify other tool versions:
# nodejs: "19"
# rust: "1.64"
# golang: "1.19"

# Build documentation with Mkdocs
mkdocs:
configuration: mkdocs.yml

# Optionally, but recommended,
# declare the Python requirements required to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
# python:
# install:
# - requirements: docs/requirements.txt
</pre>
</code>
</div>
</div>

<div class="ui bottom attached tab" data-tab="docusaurus">
<div class="ui mini padded inverted scrolling segment">
<div class="ui top attached label">
<code>.readthedocs.yaml</code>
</div>
<a class="ui top right attached icon label" href="#" data-clipboard-target="#project-create-sample-docusaurus">
<i class="fas fa-copy icon"></i>
</a>
<code class="highlight">
<pre id="project-create-sample-docusaurus">
# Read the Docs configuration file
# 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-22.04
tools:
nodejs: "19"
# You can also specify other tool versions:
# python: "3.12"
# rust: "1.64"
# golang: "1.19"

commands:
# Install Docusaurus 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/
</pre>
</code>
</div>
</div>

<div class="ui bottom attached tab" data-tab="pelican">
<div class="ui mini padded inverted scrolling segment">
<div class="ui top attached label">
<code>.readthedocs.yaml</code>
</div>
<a class="ui top right attached icon label" href="#" data-clipboard-target="#project-create-sample-pelican">
<i class="fas fa-copy icon"></i>
</a>
<code class="highlight">
<pre id="project-create-sample-pelican">
# Read the Docs configuration file
# 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-22.04
tools:
python: "3.12"
# You can also specify other tool versions:
# nodejs: "19"
# rust: "1.64"
# golang: "1.19"

commands:
# Install Pelican and its dependencies
- pip install "pelican[markdown]"
# Build the site and save generated files into Read the Docs directory
- pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html
</pre>
</code>
</div>
</div>

<div class="ui bottom attached tab" data-tab="jekyll">
<div class="ui mini padded inverted scrolling segment">
<div class="ui top attached label">
<code>.readthedocs.yaml</code>
</div>
<a class="ui top right attached icon label" href="#" data-clipboard-target="#project-create-sample-jekyll">
<i class="fas fa-copy icon"></i>
</a>
<code class="highlight">
<pre id="project-create-sample-jekyll">
# Read the Docs configuration file
# 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-22.04
tools:
ruby: "3.3"
# You can also specify other tool versions:
# python: "3.12"
# nodejs: "19"
# rust: "1.64"
# golang: "1.19"

commands:
# Install dependencies
- gem install bundle
- bundle install
# Build the site and save generated files into Read the Docs directory
- jekyll build --destination $READTHEDOCS_OUTPUT/html
</pre>
</code>
</div>
</div>

<div class="ui bottom attached tab" data-tab="others">
<div class="ui mini padded inverted scrolling segment">
<div class="ui top attached label">
<code>.readthedocs.yaml</code>
</div>
<a class="ui top right attached icon label" href="#" data-clipboard-target="#project-create-sample-others">
<i class="fas fa-copy icon"></i>
</a>
<code class="highlight">
<pre id="project-create-sample-others">
# Read the Docs configuration file
# 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-22.04
tools:
# Specify the language and version your project requires,
# by uncommenting one of the following tools.
#
# python: "3.12"
# ruby: "3.3"
# nodejs: "19"
# rust: "1.64"
# golang: "1.19"

commands:
# Write down your commands here to:
#
# - Install the dependencies of your project
# - Build the documentation
# - Save the generated files in $READTHEDOCS_OUTPUT/html
</pre>
</code>
</div>
</div>

{# Show the base form #}
Expand Down

0 comments on commit 228f122

Please sign in to comment.