Skip to content

Commit a5ed8f4

Browse files
humitosagjohnson
andauthored
Docs: mention docsify on "Build customization" (#9439)
* Docs: mention `docsify` on "Build customization" Initial minimal mention to `docsify` as an example in our "Build customization" section. Related #9435 * Apply suggestions from code review Co-authored-by: Anthony <[email protected]> * Make target names unique Co-authored-by: Anthony <[email protected]>
1 parent 4e23ab1 commit a5ed8f4

File tree

1 file changed

+37
-7
lines changed

1 file changed

+37
-7
lines changed

docs/user/build-customization.rst

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,8 @@ There are some caveats to knowing when using user-defined jobs:
7676
* ``build.os`` and ``build.tools`` are required when using ``build.jobs``
7777

7878

79-
Examples
80-
++++++++
79+
``build.jobs`` examples
80+
+++++++++++++++++++++++
8181

8282
We've included some common examples where using :ref:`config-file/v2:build.jobs` will be useful.
8383
These examples may require some adaptation for each projects' use case,
@@ -256,8 +256,23 @@ If your project requires full control of the build process,
256256
and :ref:`extending the build process <build-customization:extend the build process>` is not enough,
257257
all the commands executed during builds can be overridden using the :ref:`config-file/v2:build.commands` configuration file key.
258258

259-
For example, if your project uses `Pelican <https://blog.getpelican.com/>`_ instead of Sphinx for its documentation,
260-
your project could use the following configuration file:
259+
As Read the Docs does not have control over the build process,
260+
you are responsible for running all the commands required to install requirements and build your project properly.
261+
Once the build process finishes, the contents of the ``_readthedocs/html/`` directory will be hosted.
262+
263+
264+
``build.commands`` examples
265+
+++++++++++++++++++++++++++
266+
267+
This section contains some examples that showcase what is possible with :ref:`config-file/v2:build.commands`.
268+
Note that you may need to modify and adapt these examples depending on your needs.
269+
270+
271+
Pelican
272+
~~~~~~~
273+
274+
`Pelican <https://blog.getpelican.com/>`__ is a well-known static site generator that's commonly used for blogs and landing pages.
275+
If you are building your project with Pelican you could use a configuration file similar to the following:
261276

262277
.. code-block:: yaml
263278
:caption: .readthedocs.yaml
@@ -272,9 +287,24 @@ your project could use the following configuration file:
272287
- pelican --settings docs/pelicanconf.py --output _readthedocs/html/ docs/
273288
274289
275-
As Read the Docs does not have control over the build process,
276-
you are responsible for running all the commands required to install requirements and build the documentation properly.
277-
Once the build process finishes, the ``_readthedocs/html/`` folder will be hosted.
290+
Docsify
291+
~~~~~~~
292+
293+
`Docsify <https://docsify.js.org/>`__ generates documentation websites on the fly, without the need to build static HTML.
294+
These projects can be built using a configuration file like this:
295+
296+
.. code-block:: yaml
297+
:caption: .readthedocs.yaml
298+
299+
version: 2
300+
build:
301+
os: "ubuntu-22.04"
302+
tools:
303+
nodejs: "16"
304+
commands:
305+
- mkdir --parents _readthedocs/html/
306+
- cp --recursive docs/* _readthedocs/html/
307+
278308
279309
Search support
280310
++++++++++++++

0 commit comments

Comments
 (0)