Update docs #3498

stsewd · 2018-01-09T22:51:19Z

Probably closes:

stsewd · 2018-01-09T22:56:15Z

The most relevant commits are:

Note: the whole docs needs to be re-wrapped to 80 chars, for now I only did this for the files I touched.
Note2: This should be updated too (probably another PR) https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/base.py#L89 (the text of the autogenerated index file and the logic when to generate this file)

ericholscher · 2018-01-10T15:58:53Z

I'm generally -1 on breaking docs at 80 characters. I'd much prefer to have them broken on semantic meaning (eg. periods or commas). This has a bit more background here: http://rhodesmill.org/brandon/2012/one-sentence-per-line/, but I feel pretty strongly against just doing a straight "80 char" break.

ericholscher · 2018-01-10T16:00:24Z

I'd also ask that we not refactor content when we also change it in the PR. It makes it almost impossible to see what actually changed, so almost impossible to review.

ericholscher · 2018-01-10T16:01:46Z

In general I love docs changes though! Thanks for doing these, and I'll try and figure out what exactly is going on, so I can review it.

ericholscher · 2018-01-10T16:04:01Z

Also, we should definitely have a doc style guide, to answer questions like these :)

RichardLitt · 2018-01-11T20:27:51Z

@stsewd Can you add the doc styleguide in this PR? It can probably go in the CONTRIBUTE doc on the website if it is small, at this point.

ericholscher · 2018-01-11T20:32:08Z

We can probably steal a decent bit from here: https://github.com/writethedocs/www/blob/master/docs/style-guide.rst

stsewd · 2018-01-12T03:09:59Z

@RichardLitt I added some guidelines as suggested :). I feel like we need to improve a little more the section for contributing to the docs (and putted it a little closer to the Contributing to Read the Docs section), but probably another PR.

@ericholscher you are right, breaking the lines at semantic meaning rather that 80 chars is a good idea, the explanation from the post is very clear. Should I revert the other commits then?

This reverts commit 6e59fd0.

This reverts commit 9cf1742.

This reverts commit 6f86eec.

stsewd · 2018-01-23T21:09:13Z

docs/builds.rst

@@ -37,8 +37,6 @@ We will look inside a ``doc`` or ``docs`` directory first,
 and then look within your entire project.

 Then Sphinx will build any files with an ``.rst`` extension.
-If you have a ``README.rst``,
-it will be transformed into an ``index.rst`` automatically.

 Mkdocs


Should be MkDocs? (uppercase D)

Yeah, that's the correct way of writting it: http://www.mkdocs.org/

stsewd · 2018-01-24T17:10:05Z

I reverted the noisy commits and applied the style guide as mentioned, this is ready for another review.

humitos

Nice! Thanks @stsewd. I left a couple of comments for you to take a look :)

humitos · 2018-02-15T22:14:56Z

docs/docs.rst

@@ -10,4 +10,29 @@ You can build the docs by installing ``Sphinx`` and running::
 	# in the docs directory
 	make html

-Let us know if you have any questions or want to contribute to the documentation.
+Please follow these guidelines when updating our docs.
+Let us know if you have any questions or if something isn't clear.


Remove the if from "if something"

humitos · 2018-02-15T22:16:31Z

docs/docs.rst

+-------
+
+* Do not break the content across multiple lines at 80 characters,
+  but rather broken them on semantic meaning (e.g. periods or commas).


break them

Also, I think it would be awesome to link the post that Eric shared with you. You said that was useful to understand this idea, so may be good to link it here.

humitos · 2018-02-15T22:18:35Z

docs/faq.rst

@@ -57,7 +57,7 @@ environment, and will be set to ``True`` when building on RTD::
    {% endif %}

 I get import errors on libraries that depend on C modules
----------------------------------------------------------
+---------------------------------------------------------


Did you remove this for some reason? Just curious :)

@humitos the header is larger than the text p:

Oh, that's OK. Github doesn't show it in a monospace font for some reason:

I use rstcheck for linting rst files :)

Wow! I didn't know it and I'm a fan of @myint.

Considering that we are talking about the documentation style, I think it would be a good addition for travis checks and linting right? I mean, trigger a linting on the docs on travis checks.

Would you like to add an issue for this and take a look on what's needed and how to implement it?

Sure, I opened a new issue #3622, I will implemented later :)

stsewd · 2018-02-16T01:46:33Z

@humitos all the corrections were done, thanks!

humitos · 2018-02-16T14:21:11Z

Nice! I'm asking Eric for review this since he is the "English guy". Although, it's good enough for me.

ericholscher · 2018-02-18T02:01:58Z

Love doc updates :) 💯

RichardLitt · 2018-02-19T19:29:58Z

@humitos Feel free to ask me for English updates, too. :)

stsewd added 8 commits January 9, 2018 17:05

Update "What's available" section

a3871e3

Change title

dd24d42

Add link to getting started page

7cf9f9c

Wrap to 80 characters

6e59fd0

Remove note about changing README to index

d907524

Wrap to 80 characters

9cf1742

Fix typo

484377b

Wrap to 80 characters

6f86eec

stsewd mentioned this pull request Jan 9, 2018

README.md not found #1615

Closed

RichardLitt added Needed: documentation Documentation is required PR: work in progress Pull request is not ready for full review labels Jan 11, 2018

Add styleguide for docs

ec70855

stsewd added 7 commits January 23, 2018 15:54

Revert "Wrap to 80 characters"

344ec5c

This reverts commit 6e59fd0.

Revert "Wrap to 80 characters"

8c46050

This reverts commit 9cf1742.

Revert "Wrap to 80 characters"

4cc4d46

This reverts commit 6f86eec.

Fix header

b2f6656

Fix header

99ced33

Fix indentation

a230278

Style

db2c67a

stsewd commented Jan 23, 2018

View reviewed changes

More style changes

ae9acc6

RichardLitt added PR: ready for review and removed PR: work in progress Pull request is not ready for full review labels Jan 25, 2018

This was referenced Feb 15, 2018

Improve installation steps #3614

Closed

Update translation docs #2847

Closed

humitos reviewed Feb 15, 2018

View reviewed changes

stsewd added 2 commits February 15, 2018 20:25

Rename Mkdocs to MkDocs

57fd486

Fix grammar

c870ceb

humitos removed the Needed: documentation Documentation is required label Feb 16, 2018

humitos requested a review from ericholscher February 16, 2018 14:20

This was referenced Feb 16, 2018

Add rstcheck for linting rst files on travis #3622

Closed

Add rstcheck to CI #3624

Merged

ericholscher merged commit f725917 into readthedocs:master Feb 18, 2018

stsewd mentioned this pull request Feb 18, 2018

Need Step By Step for Creating New/Importing #2242

Closed

stsewd deleted the update-docs branch February 18, 2018 04:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs #3498

Update docs #3498

stsewd commented Jan 9, 2018 •

edited

Loading

stsewd commented Jan 9, 2018 •

edited

Loading

ericholscher commented Jan 10, 2018

ericholscher commented Jan 10, 2018

ericholscher commented Jan 10, 2018

ericholscher commented Jan 10, 2018

RichardLitt commented Jan 11, 2018

ericholscher commented Jan 11, 2018

stsewd commented Jan 12, 2018 •

edited

Loading

stsewd Jan 23, 2018

humitos Feb 15, 2018

stsewd commented Jan 24, 2018

humitos left a comment

humitos Feb 15, 2018

humitos Feb 15, 2018

humitos Feb 15, 2018

humitos Feb 15, 2018

stsewd Feb 16, 2018

humitos Feb 16, 2018

stsewd Feb 16, 2018

humitos Feb 16, 2018

stsewd Feb 16, 2018

stsewd commented Feb 16, 2018

humitos commented Feb 16, 2018

ericholscher commented Feb 18, 2018

RichardLitt commented Feb 19, 2018

Update docs #3498

Update docs #3498

Conversation

stsewd commented Jan 9, 2018 • edited Loading

stsewd commented Jan 9, 2018 • edited Loading

ericholscher commented Jan 10, 2018

ericholscher commented Jan 10, 2018

ericholscher commented Jan 10, 2018

ericholscher commented Jan 10, 2018

RichardLitt commented Jan 11, 2018

ericholscher commented Jan 11, 2018

stsewd commented Jan 12, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented Jan 24, 2018

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stsewd commented Feb 16, 2018

humitos commented Feb 16, 2018

ericholscher commented Feb 18, 2018

RichardLitt commented Feb 19, 2018

stsewd commented Jan 9, 2018 •

edited

Loading

stsewd commented Jan 9, 2018 •

edited

Loading

stsewd commented Jan 12, 2018 •

edited

Loading