Documentation on requirements.txt usage

[agjohnson]

I was surprised we don't discuss how to use requirements.txt, though it's a pretty widely used feature.

We should add a walkthrough (under guides/ for now) on how to use requirements.txt, both with our admin, but also with our readthedocs.yml file.

This would be a great place to contribute if you are a user of Read the Docs, and have some familiarity with reST or writing documentation.

[kchawla-pi]

First time aspiring contributor here (poised to dip toe in water).
I would like to help. Is this just the usual requirements.txt that pip uses or is there something special about this?
Any aspect I should be mindful of?

[RichardLitt]

@kchawla-pi Welcome! While I can't help you technically here, @humitos might be able to.

[humitos]

@kchawla-pi Hi! Thanks for showing your interest!

The idea is to write a guide on how to use the requirements.txt file in a Read the Docs project. The general idea should be covered, but also this two specific cases:

• using the yaml file: http://docs.readthedocs.io/en/latest/yaml-config.html#requirements-file
• using the project admin's web interface: Admin -> Advanced Settings -> Requirements file

Let me know if that clarifies the situation. Thanks!

[Tikam02]

while installing it i faced problem installing modules, like you have to manually install some of the modules with version wise.

[apoorvkhare07]

Is this issue still up for taking ?
Would like to work on it.

[stsewd]

@apoorvkhare07 sure, a PR is welcome.

[kchawla-pi]

I have the first draft ready for review., pending addition of doc-links .
It covers the case for:
using the project admin's web interface: Admin -> Advanced Settings -> Requirements file .
I will attend to the second use case once this is green lit.

I am having trouble using pre-commit. It is giving me the error:

 Host key verification failed.
    fatal: Could not read from remote repository.

    Please make sure you have the correct access rights
    and the repository exists.

Since I am pushing to my fork, I don't understand why I need ssh key authentication. Working to fix it.
The make html command doesn't work on windows 10. I am looking at installing make for windows.
Made the Make work, the fonts are different. Haven't been able to run pre-commit yet.

In accordance with fail fast and early, I am submitting a PR. I do not wish to increase your work and will continue to figure out making pre-commit work.

[RichardLitt]

@kchawla-pi Thanks for updating us on your progress! That particular error couldn't be the fault of Read the Docs; it must be something involving your local environment. I would troubleshoot your git instance, and see which remotes you are accessing.

[kchawla-pi]

Thanks, I'll check them.
I have documented usage of pip requirements file via admin's web interface and YAML config file.
I will create a dummy project with docs, make sure everything is working the way I wrote they do.
After that, should I include information on using a Conda environmet.yml file as well, if the user is using Conda and not venv?

[bansalnitish]

@kchawla-pi Are you still working on this. If you are not may I take this up?

[kchawla-pi]

@bansalnitish I am.

[stsewd]

@kchawla-pi could you update the PR description with "Closes #3426"? so GitHub will link this issue and others can see that you are already working on this :)

[kchawla-pi]

Thanks @stsewd . I will remember to do this in future contributions.
I have updated the pull request heading, though it is not getting hyperlinked.

[stsewd]

@kchawla-pi you only need to update the PR description, no the tittle :)

[stsewd]

Resolved in #4212