doc: add user guide #1246

saghul · 2017-03-12T22:06:13Z

As discussed in #1027, this incorporates the uvbook into our documentation.

Consider this a WIP, but I wanted to get some eyes on it early, specially I want to make sure @nikhilm is OK with the approach taken here.

@nikhilm please take a look at the commits following "doc: add initial version of the User Guide", specially the one regarding the licensing. I'm happy to make adjustments!

My plan is to do a quick pass replacing "book" with "guide", and incorporate the code examples. I won't review the entire thing in a single go. I added a warning note so the idea is to gradually improve the guide and bring it on par with latest libuv, just like we did with the API documentation.

Doc on!

PS: Sorry for being AWOL for some time, I needed some time off.

nikhilm · 2017-03-13T18:32:17Z

Thanks for this! I will take a look by Wednesday.

…

On Sun, Mar 12, 2017 at 3:06 PM, Saúl Ibarra Corretgé < ***@***.***> wrote: As discussed in #1027 <#1027>, this incorporates the uvbook into our documentation. Consider this a WIP, but I wanted to get some eyes on it early, specially I want to make sure @nikhilm <https://github.com/nikhilm> is OK with the approach taken here. @nikhilm <https://github.com/nikhilm> please take a look at the commits following "doc: add initial version of the User Guide", specially the one regarding the licensing. I'm happy to make adjustments! My plan is to do a quick pass replacing "book" with "guide", and incorporate the code examples. I won't review the entire thing in a single go. I added a warning note so the idea is to gradually improve the guide and bring it on par with latest libuv, just like we did with the API documentation. Doc on! PS: Sorry for being AWOL for some time, I needed some time off. ------------------------------ You can view, comment on, or merge this pull request online at: #1246 Commit Summary - doc: rename docs to "libuv documentation" - doc: update copyright years - doc: move TOC to a dedicated document - doc: move documentation section up - doc: move "upgrading" to a standalone document - doc: add initial version of the User Guide - doc: removed unused file - doc: update guide/about and mention new maintainership - doc: remove licensing note from guide/about - doc: add warning note to user guide File Changes - *A* docs/src/api.rst <https://github.com/libuv/libuv/pull/1246/files#diff-0> (35) - *M* docs/src/conf.py <https://github.com/libuv/libuv/pull/1246/files#diff-1> (18) - *A* docs/src/guide.rst <https://github.com/libuv/libuv/pull/1246/files#diff-2> (22) - *A* docs/src/guide/about.rst <https://github.com/libuv/libuv/pull/1246/files#diff-3> (22) - *A* docs/src/guide/basics.rst <https://github.com/libuv/libuv/pull/1246/files#diff-4> (188) - *A* docs/src/guide/eventloops.rst <https://github.com/libuv/libuv/pull/1246/files#diff-5> (48) - *A* docs/src/guide/filesystem.rst <https://github.com/libuv/libuv/pull/1246/files#diff-6> (287) - *A* docs/src/guide/introduction.rst <https://github.com/libuv/libuv/pull/1246/files#diff-7> (75) - *A* docs/src/guide/networking.rst <https://github.com/libuv/libuv/pull/1246/files#diff-8> (249) - *A* docs/src/guide/processes.rst <https://github.com/libuv/libuv/pull/1246/files#diff-9> (389) - *A* docs/src/guide/threads.rst <https://github.com/libuv/libuv/pull/1246/files#diff-10> (379) - *A* docs/src/guide/utilities.rst <https://github.com/libuv/libuv/pull/1246/files#diff-11> (433) - *M* docs/src/index.rst <https://github.com/libuv/libuv/pull/1246/files#diff-12> (61) - *A* docs/src/upgrading.rst <https://github.com/libuv/libuv/pull/1246/files#diff-13> (11) Patch Links: - https://github.com/libuv/libuv/pull/1246.patch - https://github.com/libuv/libuv/pull/1246.diff — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1246>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEzWshhzT_mjg7Oya1lV3mMf2BpBDJ4ks5rlGxmgaJpZM4Masag> .

nikhilm · 2017-03-16T04:15:39Z

docs/src/guide/index.rst

-
-    <ul>
-    <li>
-    <a href="http://nikhilm.github.com/uvbook/An%20Introduction%20to%20libuv.pdf" onClick="_gaq.push(['_trackEvent', 'Downloads', 'Download', 'PDF']);">PDF</a>


I don't know how useful the pdf/epub has been but it would be cool to continue serving these. Not a high priority of course, but sphinx does generate them for free as long as the build host has latex setup.

We server the docs with ReadTheDocs, and they already do this with an on-screen menu, see here: http://docs.libuv.org/en/v1.x/

nikhilm · 2017-03-16T04:16:10Z

docs/src/guide/about.rst

@@ -17,6 +16,10 @@ describes much of the semantics of the two libraries.
 This book was made using `Sphinx <http://sphinx.pocoo.org/>`_ and `vim
 <http://www.vim.org>`_.

+.. note::
+    In 2017 the libuv project incorporated the Nikhil's work into the official


Nit: the Nikhil's -> Nikhil's

Oh, my bad, will fix!

nikhilm · 2017-03-16T04:16:39Z

docs/src/guide/about.rst

@@ -20,9 +20,3 @@ This book was made using `Sphinx <http://sphinx.pocoo.org/>`_ and `vim
    In 2017 the libuv project incorporated the Nikhil's work into the official
    documentation and it's maintained there henceforth.

-Licensing


Could you clarify what the new licensing is going to be?

Interesting, we don't seem to have any license stated, so I guess it's MIT at the moment, like the whole project. I think a CC license makes more sense, so I'll have a look at who contributed to docs/ and ask everyone if they are ok changing it.

saghul · 2017-03-16T10:44:40Z

@nikhilm I proposed we change the license here: #1254

nikhilm · 2017-03-16T15:02:07Z

Thanks! Everything else looks great. Best, Nikhil

…

On Thu, Mar 16, 2017 at 3:44 AM, Saúl Ibarra Corretgé < ***@***.***> wrote: @nikhilm <https://github.com/nikhilm> I proposed we change the license here: #1254 <#1254> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1246 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEzWvsMUGs677hq5AyAozj7T7VMlhZ9ks5rmRKhgaJpZM4Masag> .

saghul · 2017-04-25T06:30:18Z

I think this is ready for review / landing. The guide / examples have not been adapted yet, but once we get it in it's easier to iterate quickly, and our current API documentation is a proof of that.

@libuv/collaborators PTAL.

cjihrig · 2017-04-26T13:33:31Z

docs/code/cgi/main.c

+#include <string.h>
+#include <uv.h>
+
+uv_loop_t *loop;


So, I assume this is taken directly from the book right? It should be uv_loop_t* loop, but are we going to go through and lint the whole thing by hand?

cjihrig · 2017-04-26T13:38:56Z

Is rubber stamping the book an option? Cleaning up the documentation always makes for good first contributions, which are kind of hard to come by in libuv IMO.

santigimeno · 2017-04-25T19:55:24Z

docs/code/dns/main.c

+void alloc_buffer(uv_handle_t *handle, size_t suggested_size, uv_buf_t *buf) {
+  buf->base = malloc(suggested_size);
+  buf->len = suggested_size;
+}


The indentation is not consistent in this file

Just that the uvbook is already out there. Instead of reviewing the entire book, we could take it as a known good commodity, and any necessary fixes could be made as they are discovered. That's the kind of thing that is friendly to first time contributors too.

Sure, that's what this PR is about! :-)

santigimeno · 2017-04-25T20:35:47Z

docs/src/guide/introduction.rst

+
+Since then libuv has continued to mature and become a high quality standalone
+library for system programming. Users outside of node.js include Mozilla's
+Rust_ programming language, and a variety_ of language bindings.


I think the Rust reference isn't valid anymore?

Note that this PR incorporates the book pretty much as is, those kind of fixes will follow. Same goes for the sample code.

santigimeno · 2017-04-26T13:42:38Z

Is rubber stamping the book an option? Cleaning up the documentation always makes for good first contributions, which are kind of hard to come by in libuv IMO.

I'd support this

saghul · 2017-04-26T14:14:54Z

Is rubber stamping the book an option? Cleaning up the documentation always makes for good first contributions, which are kind of hard to come by in libuv IMO.

What do you mean by this?

cjihrig · 2017-04-26T14:18:49Z

Just that the uvbook is already out there. Instead of reviewing the entire book, we could take it as a known good commodity, and any necessary fixes could be made as they are discovered. That's the kind of thing that is friendly to first time contributors too.

santigimeno

LGTM then

nikhilm · 2017-04-26T15:58:02Z

Thanks! Once this is up, I'll update my version of the book to link to this as the canonical source.

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

This is a fresh import of uvbook [0], as is. It is to be considered "beta", as the entire content hasn't been revised / adapted yet. PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

We use guide.rst as our index, so there is no need for a secondary one. PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

Text taken from: https://creativecommons.org/licenses/by/4.0/legalcode.txt Fixes: libuv#1254 PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

PR-URL: libuv/libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

nikhilm reviewed Mar 16, 2017

View reviewed changes

saghul mentioned this pull request Mar 17, 2017

doc: re-license documentation as CC By 4.0 #1254

Closed

saghul force-pushed the doc-user-guide branch from 135b031 to 6bbb753 Compare April 25, 2017 06:28

saghul added this to the 1.12.0 milestone Apr 25, 2017

saghul requested review from bnoordhuis, santigimeno and cjihrig April 26, 2017 06:31

cjihrig reviewed Apr 26, 2017

View reviewed changes

santigimeno reviewed Apr 26, 2017

View reviewed changes

santigimeno approved these changes Apr 26, 2017

View reviewed changes

cjihrig approved these changes Apr 26, 2017

View reviewed changes

saghul added 8 commits April 28, 2017 11:13

doc: rename docs to "libuv documentation"

93415e6

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

doc: update copyright years

d2eca71

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

doc: move TOC to a dedicated document

8e95cba

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

doc: move documentation section up

afb37ce

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

doc: move "upgrading" to a standalone document

521146d

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

doc: removed unused file

a94f83e

We use guide.rst as our index, so there is no need for a secondary one. PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

doc: update guide/about and mention new maintainership

1caae80

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

saghul added 5 commits April 28, 2017 11:15

doc: remove licensing note from guide/about

481f454

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

doc: add warning note to user guide

0227060

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

doc: change license to CC BY 4.0

ed76c05

Text taken from: https://creativecommons.org/licenses/by/4.0/legalcode.txt Fixes: libuv#1254 PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

doc: remove ubvook reference from README

2ce5734

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

doc: add code samples from uvbook (unadapted)

d59d6e6

PR-URL: libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

saghul force-pushed the doc-user-guide branch from 6bbb753 to d59d6e6 Compare April 28, 2017 09:16

saghul merged commit d59d6e6 into libuv:v1.x Apr 28, 2017

saghul deleted the doc-user-guide branch April 28, 2017 09:17

inkydragon pushed a commit to one-pr/Chinese-uvbook that referenced this pull request Dec 16, 2021

doc: add code samples from uvbook (unadapted)

266dcfe

PR-URL: libuv/libuv#1246 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add user guide #1246

doc: add user guide #1246

saghul commented Mar 12, 2017

nikhilm commented Mar 13, 2017 via email

nikhilm Mar 16, 2017

saghul Mar 16, 2017

nikhilm Mar 16, 2017

saghul Mar 16, 2017

nikhilm Mar 16, 2017

saghul Mar 16, 2017

saghul commented Mar 16, 2017

nikhilm commented Mar 16, 2017 via email

saghul commented Apr 25, 2017

cjihrig Apr 26, 2017

cjihrig commented Apr 26, 2017

santigimeno Apr 25, 2017

saghul Apr 26, 2017

santigimeno Apr 25, 2017

saghul Apr 26, 2017

santigimeno commented Apr 26, 2017

saghul commented Apr 26, 2017

cjihrig commented Apr 26, 2017

santigimeno left a comment

nikhilm commented Apr 26, 2017

doc: add user guide #1246

doc: add user guide #1246

Conversation

saghul commented Mar 12, 2017

nikhilm commented Mar 13, 2017 via email

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

saghul commented Mar 16, 2017

nikhilm commented Mar 16, 2017 via email

saghul commented Apr 25, 2017

Choose a reason for hiding this comment

cjihrig commented Apr 26, 2017

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

santigimeno commented Apr 26, 2017

saghul commented Apr 26, 2017

cjihrig commented Apr 26, 2017

santigimeno left a comment

Choose a reason for hiding this comment

nikhilm commented Apr 26, 2017