Skip to content
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

More tips about how to reduce resources usage #4419

Merged
merged 2 commits into from
Aug 22, 2018
Merged

More tips about how to reduce resources usage #4419

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ddb6f19
More tips about how to reduce resources usage
humitos Jul 24, 2018
a74ec85
Expand the docs and fix typos
humitos Aug 13, 2018
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
30 changes: 29 additions & 1 deletion docs/guides/build-using-too-many-resources.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Reduce formats you're building

You can change the formats of docs that you're building with our YAML file's :ref:`yaml-config:Formats` option.

In particular, the `htmlzip` takes up a decent amount of memory and time,
In particular, the ``htmlzip`` takes up a decent amount of memory and time,
so disabling that format might solve your problem.

Reduce documentation build dependencies
Expand All @@ -23,3 +23,31 @@ If there are extra packages that you don't need for building docs,
you can create a custom requirements file just for documentation.
This should speed up your documentation builds,
as well as reduce your memory footprint.

Use pip when possible
---------------------

If you don't need ``conda`` to create your *documentation* environment,
consider using ``pip`` instead since ``conda`` could `require too much memory`_ to calculate the dependency tree
when using multiple channels.

.. _require too much memory: https://github.com/conda/conda/issues/5003>


.. tip::

Even though your *project* environment is created with ``conda``, it may be not necessary for the *documentation* environment.
That is, to build the documentation is probably that you need fewer Python packages than to use your library itself.
So, in this case, you could use ``pip`` to install those fewer packages instead of creating a big environment with ``conda``.


Use system site-packages for pre-installed libs
-----------------------------------------------

There are a few libraries that Read the Docs has already installed (scipy, numpy, matplotlib, pandas, etc)
in the Docker image used to build your docs. You can check the updated list of pre-installed libraries in the `Docker image repository`_.
Copy link
Contributor

Choose a reason for hiding this comment

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

We probably need to document which exact libraries are available. I don't think it's reasonable for people to have to dig through a git repo for this data.

Copy link
Member Author

Choose a reason for hiding this comment

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

Do we want to document this here or in the specific YAML config at #4422 ?

Also, this depends on the Docker Image used itself so, I'm not sure that there is a generic way to document this and keep it updated. That's why I mentioned them generally and points to the repository.

Copy link
Member

Choose a reason for hiding this comment

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

I think documenting this in the yaml config makes sense, or maybe on another central doc, because we'll be having multiple versions, and each with the same content about build images.


To use these pre-installed libraries and avoid consuming time re-downloading/compiling them,
you can use the :ref:`yaml-config:python.use_system_site_packages` option to have access to them.

.. _Docker image repository: https://github.com/rtfd/readthedocs-docker-images