From f4026938255b1f456d501e963baab7a394f9239a Mon Sep 17 00:00:00 2001 From: "Kshitij Chawla (kchawla-pi)" Date: Sun, 18 Feb 2018 17:12:58 -0500 Subject: [PATCH 1/3] Add guide for requirements from #3636 The original PR got confused about files changes. I cherry picked these from the history. Hopefully this is most of the changes Closes #3636 --- docs/faq.rst | 2 + docs/guides/index.rst | 1 + docs/guides/specifying-dependencies.rst | 67 +++++++++++++++++++++++++ 3 files changed, 70 insertions(+) create mode 100644 docs/guides/specifying-dependencies.rst diff --git a/docs/faq.rst b/docs/faq.rst index d21cf1039f0..75d089d2fee 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -185,6 +185,8 @@ are `numpydoc `_ and output more closely matches the format of standard Sphinx annotations, and as a result, it tends to look a bit better with the default theme. +.. _faq_document_package_not_at_root: + Can I document a python package that is not at the root of my repository? ------------------------------------------------------------------------- diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 6cf2a0e09bb..2ac88cb8b99 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -5,6 +5,7 @@ These guides will help walk you through the usage of Read the Docs. .. toctree:: + :maxdepth: 1 :glob: * diff --git a/docs/guides/specifying-dependencies.rst b/docs/guides/specifying-dependencies.rst new file mode 100644 index 00000000000..a03e476481d --- /dev/null +++ b/docs/guides/specifying-dependencies.rst @@ -0,0 +1,67 @@ +Specifying Dependencies +======================= + +Any dependencies required for building a documentation project can be specified using a pip requirements file or a conda environment file. + +.. note:: For the purpose of building your documentation with RTD, *project* is the documentation project, and *project root* is the directory where all the documentation is stored, often named ``docs``. + +Specifying a requirements file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The requirements file option is useful for specifying dependencies required for building the documentation. Additional uses specific to Read the Docs are mentioned at the end of this guide. + +For details about the purpose of pip requirements file and how to create one, check out `pip user guide`_ + +To use the requirements file, create and place the requirements file in the root directory of your documentation directory. For example:: + + docs/requirements.txt + +Using the YAML configuration file +--------------------------------- +The recommended approach for specifying a pip requirements file is to use a readthedocs.yml file. + +The file's path should be relative to documentation root. + +.. code-block:: yaml + + requirements_file: requirements.txt + +See :doc:`yaml-config` for setting up the .yml file + +Using the project admin dashboard +--------------------------------- + +Once the requirements file has been created; + +- Login to Read the Docs and go to the project admin dashboard. +- Go to ``Admin > Advanced Settings > Requirements file``. +- Specify the path of the requirements file you just created. The path should be relative to the root directory of the documentation project. + +Using a conda environment file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If using conda, the dependencies can be specified in the conda environment file, ``environment.yml`` . + +More on Read the Doc's conda support: :doc:`conda` + +Working with `conda and environment.yml`_ + +.. note:: Conda is only supported via the YAML file. + +This conda environment file can be specified in ``readthedocs.yml`` in the ``conda`` block. + +.. code-block:: yaml + + conda: + file: environment.yml + +As before, the path should be relative to the documentation repository root. + +Additional Uses +~~~~~~~~~~~~~~~ + - Documenting multiple packages + - setup.py not in root directory + +See :ref:`faq_document_package_not_at_root` + + +.. _`pip user guide`: : https://pip.pypa.io/en/stable/user_guide/#requirements-files +.. _`conda and environment.yml`: : https://conda.io/docs/user-guide/tasks/manage-environments.html From 56280b37e3bf92952fd984989ca578fb6eb01763 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Fri, 15 Jun 2018 11:58:25 +0100 Subject: [PATCH 2/3] Cleanup from review --- docs/faq.rst | 2 -- docs/guides/specifying-dependencies.rst | 21 ++++++++------------- 2 files changed, 8 insertions(+), 15 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index 75d089d2fee..d21cf1039f0 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -185,8 +185,6 @@ are `numpydoc `_ and output more closely matches the format of standard Sphinx annotations, and as a result, it tends to look a bit better with the default theme. -.. _faq_document_package_not_at_root: - Can I document a python package that is not at the root of my repository? ------------------------------------------------------------------------- diff --git a/docs/guides/specifying-dependencies.rst b/docs/guides/specifying-dependencies.rst index a03e476481d..c9ffba37e1e 100644 --- a/docs/guides/specifying-dependencies.rst +++ b/docs/guides/specifying-dependencies.rst @@ -7,6 +7,7 @@ Any dependencies required for building a documentation project can be specified Specifying a requirements file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The requirements file option is useful for specifying dependencies required for building the documentation. Additional uses specific to Read the Docs are mentioned at the end of this guide. For details about the purpose of pip requirements file and how to create one, check out `pip user guide`_ @@ -17,7 +18,8 @@ To use the requirements file, create and place the requirements file in the root Using the YAML configuration file --------------------------------- -The recommended approach for specifying a pip requirements file is to use a readthedocs.yml file. + +The recommended approach for specifying a pip requirements file is to use a ``readthedocs.yml`` file. The file's path should be relative to documentation root. @@ -38,6 +40,7 @@ Once the requirements file has been created; Using a conda environment file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + If using conda, the dependencies can be specified in the conda environment file, ``environment.yml`` . More on Read the Doc's conda support: :doc:`conda` @@ -50,18 +53,10 @@ This conda environment file can be specified in ``readthedocs.yml`` in the ``con .. code-block:: yaml - conda: - file: environment.yml + conda: + file: environment.yml As before, the path should be relative to the documentation repository root. -Additional Uses -~~~~~~~~~~~~~~~ - - Documenting multiple packages - - setup.py not in root directory - -See :ref:`faq_document_package_not_at_root` - - -.. _`pip user guide`: : https://pip.pypa.io/en/stable/user_guide/#requirements-files -.. _`conda and environment.yml`: : https://conda.io/docs/user-guide/tasks/manage-environments.html +.. _`pip user guide`: https://pip.pypa.io/en/stable/user_guide/#requirements-files +.. _`conda and environment.yml`: https://conda.io/docs/user-guide/tasks/manage-environments.html From 43363fb2ac033a31b010a9efba1bde793db4c5de Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Fri, 15 Jun 2018 11:59:12 +0100 Subject: [PATCH 3/3] Missed a period --- docs/guides/specifying-dependencies.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/specifying-dependencies.rst b/docs/guides/specifying-dependencies.rst index c9ffba37e1e..0eb208742e7 100644 --- a/docs/guides/specifying-dependencies.rst +++ b/docs/guides/specifying-dependencies.rst @@ -10,7 +10,7 @@ Specifying a requirements file The requirements file option is useful for specifying dependencies required for building the documentation. Additional uses specific to Read the Docs are mentioned at the end of this guide. -For details about the purpose of pip requirements file and how to create one, check out `pip user guide`_ +For details about the purpose of pip requirements file and how to create one, check out `pip user guide`_. To use the requirements file, create and place the requirements file in the root directory of your documentation directory. For example::