Added documentation for using a pip requirements file. #3636

kchawla-pi · 2018-02-18T23:46:37Z

Closes #3426
Created docs/guides/requirements-file with documentation on using a pip requirements file.

I have been unable to run pre-commit and am working to fix it. I will withdraw this pull request and submit a fresh one then.
The make html command is giving incorrect fonts, the standard Time New Roman, although it is displaying the correct fonts when I visit the website.
Next step is to attend to documentation for using the yaml file: http://docs.readthedocs.io/en/latest/yaml-config.html#requirements-file.
Help and feedback appreciated.

…ias_before_slug

stsewd · 2018-02-19T00:08:28Z

docs/guides/using-requirements-file.rst

@@ -0,0 +1,104 @@
+Read the Docs: Using a requirements file


I think the Read the Docs prefix isn't necessary, and we use title-case for h1 headers

stsewd · 2018-02-19T00:15:08Z

docs/guides/using-requirements-file.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Now, once the requirements file has been created for either scenario;
+
+- Login to your Read the Docs project ( you have to be admin of the project).


There is a trailing whitespace on the (

stsewd · 2018-02-19T00:16:52Z

docs/guides/using-requirements-file.rst

+- From the list of your Read the Docs projects, click on the project you wish to modify.
+- Click on the Admin button along the top row.
+- Go to advanced settings.
+- Enable the option ``Install your project inside a virtualenv using setup.py install``.


The install project option is not mandatory for using the requirements file option

stsewd · 2018-02-19T00:19:03Z

Thanks for your contribution, RTD have some guidelines when contributing to the documentation, take a look at https://docs.readthedocs.io/en/latest/docs.html.

Running pre-commit here isn't necessary, this is just for code.

- Removed line `Enable the option Install your project inside a virtualenv using setup.py install.` - Rewrote the section `Using the requirements file` to less verbose. - Changed H1 heading to Title Case.

stsewd · 2018-02-19T06:14:10Z

@kchawla-pi why did you close this PR? You can still working on this without closing it :)

kchawla-pi · 2018-02-19T06:39:52Z

Huh. :-) Good to know. Thanks.
I made and pushed the changes from your review.
Currently working on the second yaml file case.

- Added label `.. _faq_document_package_not_at_root` for section `Can I document a python package that is not at the root of my repository?`

- Added reference to label `faq_document_package_not_at_root` in `faq.rst`. - Changed heading for section on using requirements file via web admin interface. - Removed the `/` at the root of example paths.

kchawla-pi · 2018-02-19T23:57:43Z

Added section on how to use requirements file via a YAML file, and made some refinements to text from previous commits.
Somehow I copy-pasted text between editors and git marked the entire file's contents as new, or something. Not sure how , or how to fix that. Sorry about that.

davidfischer

This is a thorough guide!

Because of the multiple levels of headings, this guide really monopolizes the guides page. Let's add :maxdepth: 1 in guides/index.rst to keep that page cleaner.

davidfischer · 2018-02-20T23:59:41Z

docs/guides/using-requirements-file.rst

+ - You have multiple python packages in your project and you wish to document them.
+
+-----------------------------
+Using a pip requirements file


This duplicates the top heading. I think it can safely be removed.

davidfischer · 2018-02-21T00:17:43Z

docs/guides/using-requirements-file.rst

+
+You have enabled the install project in a virtual environment option, but your package's setup.py file is not in the root directory.
+---------------------------------------------------------------------------------------------------------------------------------------
+OR


These are headers with permalinks. A shorter heading would be better.

davidfischer · 2018-02-21T00:17:52Z

docs/guides/using-requirements-file.rst

+Creating the requirements file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You are using external packages, extensions, and themes that you need to include in your documentation project


This heading is very long and probably should probably be shorter. I realize the idea was to match the 3 cases outlined in the first section but perhaps something like "Supporting external packages, extensions, and themes" would work.

davidfischer · 2018-02-21T00:23:16Z

docs/guides/using-requirements-file.rst

+You are using external packages, extensions, and themes that you need to include in your documentation project
+---------------------------------------------------------------------------------------------------------------
+
+Read the Docs supports adding specific functionality, and themes to tailor the behavior and appearance


The comma here is unnecessary.

davidfischer · 2018-02-21T00:24:05Z

docs/guides/using-requirements-file.rst

+---------------------------------------------------------------------------------------------------------------
+
+Read the Docs supports adding specific functionality, and themes to tailor the behavior and appearance
+of your project's documentation. This is done by specifying a list of the packages, extensions, themes, to be used,


"packages, extensions, themes, to be used," -> "packages, extensions, and themes to be used"

davidfischer · 2018-02-21T00:24:41Z

docs/guides/using-requirements-file.rst

+To do this, one can create a list of requirements and save it in a requirements file.
+
+Since *RTD* uses Python language to build the workflow which automatically converts and hosts your project's
+documentation, and uses various python packages for this, the requirments file is the same as any standard python project.


"requirments" -> "requirements"

davidfischer · 2018-02-21T00:24:58Z

docs/guides/using-requirements-file.rst

+
+To do this, one can create a list of requirements and save it in a requirements file.
+
+Since *RTD* uses Python language to build the workflow which automatically converts and hosts your project's


"uses Python language" -> "uses the Python language"

- Used different character for section underlines for better visual separation of sections.

- Added :maxdepth: 1 to prevent cluttering index.rst with guides/using-requirements-file.rst subheadings.

- Formatted headings to be more visually distinct among levels. - Removed redundant heading `Using the pip requirements file`. - Reduced verbosity of headings. - Fixed grammar errors and typos.

- Added clarification about the meaning of project and project root.

- Sharpened the focus of the documentation to only using the feature. - Replaced background and redundant information with appropriate links. - Removed (outdated) warnings about beta status of `conda` support.

…ies.rst

….org into requirements-file

kchawla-pi · 2018-03-30T21:17:50Z

Alright, I think I rebased correctly, didn't set my hair on fire, the build is passing. My make html is now glitching. Not sure why. My virtualenv was active.
Attaching the error logs i saved when trying to make from git bash and cmd.
sphinx-err-olqmm5.log
sphinx-err-abix_5.log

File "c:\python27\Lib\importlib\__init__.py", line 37, in import_module
    __import__(name)
ImportError: No module named dj_pagination

kchawla-pi · 2018-03-30T21:34:44Z

Phew! Turns out, I could have 99 problems but a rebase ain't one.
I don't have 99 problems either, so pretty sweet.

humitos · 2018-04-02T23:06:14Z

ImportError: No module named dj_pagination

It seems that you created and installed some packages in your venv but then the requirements file changed and new packages needs to be installed.

You can:

re-create the venv (preffered)
re install dependencies: pip install -r requirements.txt

kchawla-pi · 2018-04-15T03:02:00Z

BUMP!

stsewd · 2018-04-15T04:16:36Z

@kchawla-pi it seems that something went wrong with the rebase, the diff shows that 180 files were modified.

kchawla-pi · 2018-04-15T15:07:35Z

It included all the commits made since the original fork I believe. Isn't that what a rebase does, move the commit history to the head so it appears seamless? How do I address this? The checks indicate that it doesn't damage anything, and can be merged. What should I do?

kchawla-pi · 2018-04-15T22:23:18Z

Should I open a new pull request in a new branch, with only the final changes made for the documentation?

kchawla-pi · 2018-04-29T14:01:29Z

I hadn't pulled from the upstream master in a while. I did when I failed the Travis tests and pulled the upstream mater to my forked master. Is it not probable that 180 files would have changed in the intervening period? The tests are passing.
Any reviewers out there?

RichardLitt · 2018-04-29T15:59:16Z

We'll review this when we have time, @kchawla-pi. I suspect that there was something wrong with the rebase; it's not normal to have commits from other authors in your branch after a rebase. However, the maintainers have limited time and effort, so there may be a gap before we're able to help and review this PR. Please be patient. Thanks.

stsewd · 2018-05-10T19:06:33Z

Should I open a new pull request in a new branch, with only the final changes made for the documentation?

I think this is the best option here since I'm not sure if there is an easy way to solve the rebase error. If you do so, please link to this PR, so the review isn't lost :). Thanks for working on this!

stsewd · 2018-06-06T17:59:40Z

@kchawla-pi are you still interested in opening a new PR with the changes?

The original PR got confused about files changes. I cherry picked these from the history. Hopefully this is most of the changes Closes #3636

agjohnson · 2018-06-08T21:24:17Z

👍 for a new PR, I've cherry picked the commits and fixed the rebase in #4212.

ericholscher · 2018-06-15T11:00:18Z

Merging this in #4212 👍

Add guide for requirements from #3636

kchawla-pi · 2018-07-05T14:22:44Z

I apologize for not attending to this, and more so for not informing the people here about my inability to do so.

RichardLitt · 2018-07-05T16:55:49Z

@kchawla-pi Thanks for checking back in and having the courage to say that! It is appreciated. :)

funkyHat and others added 9 commits April 10, 2017 15:02

check for matching alias before subproject slug

9130f38

fixes readthedocs#2731

Merge remote-tracking branch 'origin/master' into subproject_check_al…

e07be83

…ias_before_slug

Address PR comments

c3d2ddc

Improve "Sharing" docs

d2d4a1e

use get_object_or_404 shortcut

a4bb8e3

revert style changes (where did they even come from?)

9bb0f28

Merge remote-tracking branch 'origin/master' into subproject_check_al…

6a66934

…ias_before_slug

fixed formatting buttons in edit project text editor

828ec8a

Added documentation for using a pip requirements file

9938805

stsewd reviewed Feb 19, 2018

View reviewed changes

kchawla-pi closed this Feb 19, 2018

Fixed issues pointed out in first pull request review

70f5625

- Removed line `Enable the option Install your project inside a virtualenv using setup.py install.` - Rewrote the section `Using the requirements file` to less verbose. - Changed H1 heading to Title Case.

kchawla-pi reopened this Feb 19, 2018

humitos and others added 5 commits February 19, 2018 13:14

Fix SVN initialization for command logging (readthedocs#3638)

648e6fd

Added label for Can I document ... root of my repository

235c8b6

- Added label `.. _faq_document_package_not_at_root` for section `Can I document a python package that is not at the root of my repository?`

Added `Using pip requirments file with a YAML config file

d05bd73

- Added reference to label `faq_document_package_not_at_root` in `faq.rst`. - Changed heading for section on using requirements file via web admin interface. - Removed the `/` at the root of example paths.

Fixed label faq_document_package_not_at_root

7d793e4

Update RTD security docs

46d543a

Fix a 500 when searching for files with API v1

56c8f4c

davidfischer requested changes Feb 21, 2018

View reviewed changes

kchawla-pi added 4 commits February 20, 2018 20:46

Changed section header underlines

d7c779a

- Used different character for section underlines for better visual separation of sections.

Added :maxdepth: 1

53b87a4

- Added :maxdepth: 1 to prevent cluttering index.rst with guides/using-requirements-file.rst subheadings.

Fixed: Headings and body text, typos

8aa1da2

- Formatted headings to be more visually distinct among levels. - Removed redundant heading `Using the pip requirements file`. - Reduced verbosity of headings. - Fixed grammar errors and typos.

Added clarification + language & punctuation tweaks

70cc65d

- Added clarification about the meaning of project and project root.

kchawla-pi added 9 commits March 30, 2018 16:51

Added clarification + language & punctuation tweaks

251945b

- Added clarification about the meaning of project and project root.

Removed redundant/verbose text from first section

9be835a

Added section for using conda environment.yml

c7c2e05

Fixed :doc: referrer to conda.rst

22fceec

Fixed minor typo and formatting

0d78a94

Simplified the documentation siginificantly

31581e4

- Sharpened the focus of the documentation to only using the feature. - Replaced background and redundant information with appropriate links. - Removed (outdated) warnings about beta status of `conda` support.

Fixed yaml code block formatting

dc1159c

Update and rename using-requirements-file.rst to specifying-dependenc…

887c25b

…ies.rst

Merge branch 'requirements-file' of github.com:kchawla-pi/readthedocs…

ddda401

….org into requirements-file

agjohnson pushed a commit that referenced this pull request Jun 8, 2018

Add guide for requirements from #3636

f402693

The original PR got confused about files changes. I cherry picked these from the history. Hopefully this is most of the changes Closes #3636

agjohnson mentioned this pull request Jun 8, 2018

Add guide for requirements from #3636 #4212

Merged

agjohnson approved these changes Jun 8, 2018

View reviewed changes

agjohnson removed the PR: ready for review label Jun 8, 2018

ericholscher closed this Jun 15, 2018

ericholscher added a commit that referenced this pull request Jun 15, 2018

Merge pull request #4212 from rtfd/agj/requirements-docs-fixup

bd9cd6a

Add guide for requirements from #3636


		To do this, one can create a list of requirements and save it in a requirements file.

		Since RTD uses Python language to build the workflow which automatically converts and hosts your project's

Uh oh!

Added documentation for using a pip requirements file. #3636

Added documentation for using a pip requirements file. #3636

Uh oh!

Conversation

kchawla-pi commented Feb 18, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stsewd commented Feb 19, 2018

Uh oh!

stsewd commented Feb 19, 2018

Uh oh!

kchawla-pi commented Feb 19, 2018

Uh oh!

kchawla-pi commented Feb 19, 2018

Uh oh!

davidfischer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kchawla-pi commented Mar 30, 2018

Uh oh!

kchawla-pi commented Mar 30, 2018

Uh oh!

humitos commented Apr 2, 2018

Uh oh!

kchawla-pi commented Apr 15, 2018

Uh oh!

stsewd commented Apr 15, 2018

Uh oh!

kchawla-pi commented Apr 15, 2018

Uh oh!

kchawla-pi commented Apr 15, 2018

Uh oh!

kchawla-pi commented Apr 29, 2018

Uh oh!

RichardLitt commented Apr 29, 2018

Uh oh!

stsewd commented May 10, 2018

Uh oh!

stsewd commented Jun 6, 2018

Uh oh!

agjohnson commented Jun 8, 2018

Uh oh!

ericholscher commented Jun 15, 2018

Uh oh!

kchawla-pi commented Jul 5, 2018

Uh oh!

RichardLitt commented Jul 5, 2018

Uh oh!

Uh oh!

kchawla-pi commented Feb 18, 2018 •

edited

Loading