One doc to rule them all #597
Conversation
docs/build/Build-Script.md
Outdated
|
|
||
| -- | ||
| #### `--clean` | ||
| With given this option, build.py will claer all the build directory before start new build. |
docs/devs/Inside-IoT.js.md
Outdated
|
|
||
| ## iotjs_handlewrap_t | ||
|
|
||
| `iotjs_handlewrap_t` is to bind a Javascript object and a libuv handle(e.g. file descriptor) together. |
There was a problem hiding this comment.
IMHO whitespace maybe required
docs/devs/Inside-IoT.js.md
Outdated
| 7. Builtin after handler release `iotjs_reqwrap_t` by calling `iotjs_*reqwrap_dispatch()` | ||
|
|
||
| `iotjs_reqwrap_t` does not inherits `iotjs_handlewrap_t` for wrapping the callback function object. | ||
| Note that `HandleWrap` does not increase reference count of wrapping object. it does not guarantee guarantee liveness of the object even if the wrapper is alive. |
docs/devs/Inside-IoT.js.md
Outdated
| Thus in the above example 'requested' will be printed out right after file open request was made. | ||
|
|
||
| If there were I/O requests, `uv_run()` in the main loop waits by polling the requests until at least one of the request processing were finished. | ||
| When a result for a request was produced, internal part of libuv calls corresponding handler function(let it be after function) back. |
docs/help/Developer-Tutorial.md
Outdated
|
|
||
| Pretty simple. But where did `console` come from? `console` is not defined in Global Object according to ECMAScript spec. | ||
|
|
||
| The answer is `console` is a builtin module so it should have been `require`ed. However, `console` is a special case so we can use it directly without `require`. This is about Module System which We will cover later. |
|
I did quick changes based on the comments, but the purpose of this change is to introduce new logic in the documentation instead to change the relevant content. This - the update of the text - can be done later, but first it should be agreed which way the docs of IoT.js will be presented. |
|
It would be better you make this PR with one single commit |
The final goal is to combine different guides and documentation scattered various places to a common one. This commit does the followings: - create new folders to introduce some logic here - copy the Wiki pages to the repository - update the links and references in the MD files. - do quick typo fixes IoT.js-DCO-1.0-Signed-off-by: Gabor Loki loki@inf.u-szeged.hu
loki04
force-pushed
the
one-doc-to-rule-them-all
branch
from
b22c334 to
334fc4a
Compare
|
Here it is! One commit for one doc! ;) |
|
Thank you for this PR. One doc plan is great! I hope it works well. Here are some questions about executing the plan.
|
|
In short there is no need for the Wiki in this form. The only extra is the sidebar in the Wiki compared to any MD file in the repository. In other hand the repository-based documentation has a not negligible advantage: there will be a review via pull request which is totally missing at the Wiki right now. What I suggested in the #596 is more than what you can see in this PR. The link which describes the two way modification of Wiki is a robust solution to take control of each documentation changes, but it is not necessary. Let's discuss the details there if there is a need for such a solution. If you have concerns about the security you can still create an artificial account with a very limited permissions to do deal with the synchronization. This PR is not about to solve #596 , instead create something which can stand on its own feet, and can be the basic of a new repository if you are about to move the documentation to a separate repository. About your 2nd question... the plan is simple:
|
|
@loki04 I have a question about your plan number 3. If we follow your plan, we can't use Wiki menu bar, right? (see below screenshot)
I think this is very useful feature of Wiki page. (We can check all pages in here, and also can see a hierarchy of all documents. Do you have any idea about it? |
|
@nova0821 Yes, this is the sidebar ( https://guides.github.com/features/wikis/ ). I can confirm that between action steps 3-5, you will not able to use the sidebars, since there will be no Wiki pages. If the community has the decision to adopt the synchronization method between a separate repository and the wiki ( #597 ) you will be able to use the sidebar again. |
|
@loki04 I also wanted to remove wiki pages when I joined this project first. So I asked some member who joined this project before me. "Why do we keep wiki pages that is same to docs?", I got the answer that documents in github source repository are not searched in google. Besides the wiki documents could be. After doing several google searches related to iotjs, I agreed to keep our documents in both of the iotjs repo and wiki repo. About the wiki review process, we have kept the policy of creating/updating documents in iotjs repo first, then applying the reviewed and merged documents into wiki. We don't need the duplicated review process for wiki. In summary,
|
|
@glistening , you are wrong about the indexing method of Google. The search engines can index the master branch of any repository (except the owner of the repository prevents this). Here is the main info about it: https://github.com/robots.txt . I can confirm that the search engines are able to index the master branch. I have several public repositories indexed by Google, and checked several organizations' repositories which have been indexed successfully. So, I think the reason why Google is not able to index iot.js master branch is that the owner of the project (or the organization) prevents the indexing. On the other hand if the wiki contained the exact content of the Anyhow, this just a pull request which tries to combine different descriptions, guides, and notes from Wiki, and to do some reorganization of them. So, I suggest to do general discussion about Wiki, github's pages and docs on #596 issue instead. Let this PR as it is to merge the content. |
|
Thank you for information about the index method of Google. We need to find out the reason of not indexing of our master branch (including organization policy). About your comment "no synchronous update on them", in fact, we continuously made efforts to synchronize About mering this PR, if we merge this PR, we must apply these changes also to wiki pages. If we merge only this one, we are out of synchronous state on the duration. It cannot be done by merely copying them. We must check whether there is broken link, and update sidebars. And if we made the decision of not keeping wiki pages based on your information and suggestion, the synchronizing work is not necessary. I will gather other member's opinions. Thank you. |
|
I confirmed that iotjs master branch is searchable in Google. I tried to find the page |
|
I discussed with other members. Although it turned out that documents in master branch are searchable, they prefer to keep wiki pages for user's perspective. (e.g., easy navigation, ...) Therefore we need a way to synchronize between iotjs repo and wiki on the condition of keeping wiki pages. Currently my plan is following: (1) I will begin to apply this PR to wiki. (i.e., applying pages, and checking the validity of urls, and updating sidebar) (2) In duration of (1), I will gather the exceptional cases that needs manual merging during this work. (3) We will merge this PR (#597) (4) If possible, we will make a script for synchronizing automatically. (It will be another PR.) (5) It would be better to trigger script of (4) automatically whenever docs are modified. It may be based on your first suggestion (using separate doc repository). It will be yet another PR. Thank you. |
glistening
left a comment
glistening
left a comment
There was a problem hiding this comment.
LGTM. I will apply this changes to wiki later.
|
LGTM. We will update WiKi pages along with this new restructuring |
6 participants
Restructure docs folder. (#596)
The final goal is to combine different guides and documentation scattered
various places to a common one.
This commit does the followings: