Trying to create new docs - wont index

[defel]

Hi,

I need a jump-start again.

I am trying to create new documentation for protractor. As there are no good api-docs for protractor in markdown-format on github, I want to paste them hand-crafted from angular.github.io/protractor to the docs/ folder.

What I have done:

• create no subfolder docs/protractor
• create two files: docs/protractor/element/all/index.md and docs/protractor/element/index.md
• copied config.json from docs/js to docs/protractor and edited it to contains both functions 'element' and 'element/all'
• run indexin wat -> nothing happens
• run gulp index on shell -> nothing happens

What have I exactly to do, to add this new docs?

For me it looks on the first view exactly like the js doc. The files config/config.json and config/index.json were also updated automatically by index command.

For clarity you can see the wip here: https://github.com/defel/wat/tree/protractor-docs/docs/protractor

[dthree]

Hey. Checking this out right now.

[dthree]

When you do gulp index, Does it say: Wat: Rebuilt Index.? Does it give any message at all?

[defel]

Yes. The output of gulp index was:

[18:45:11] Using gulpfile ~/code/wat/gulpfile.js
[18:45:11] Starting 'initClerk'...
? [18:45:12] Finished 'initClerk' after 482 ms
[18:45:12] Starting 'buildIndex'...

           Wat: Rebuilt index.

The output of index inside of wat was:

Successfully updated index.

I start wat by ./bin/index.js

Thank you!

[dthree]

Ah thanks.

Can you pls run gulp index and then don't do index afterwards, and then do a git status and tell me what was changed?

The index command inside wat is a user command that pulls the present index from the Github repo, so it "overwrites" any local index you are making.

The gulp index command writes the local index in the actual Wat directory, as opposed to Wat's temp directory.

So it should have written an index in ./config/index.json

[dthree]

Yeah - I just cloned your branch and tried this, and this was the case.

It is successfully writing your updates in the index. The problem is that you wont see them until you push the updates up to Github. That's my problem, which I'll fix right now.

[defel]

Yes, the output is:

$ git status                                                                                                                                                                                                                                                              
# On branch protractor-docs                                                 
nothing to commit (working directory clean)                                 

$ gulp index                                                                
[18:53:08] Using gulpfile ~/code/wat/gulpfile.js                            
[18:53:08] Starting 'initClerk'...                                          
? [18:53:08] Finished 'initClerk' after 487 ms                              
[18:53:08] Starting 'buildIndex'...                                         

           Wat: Rebuilt index.                                              



$ git status                                                                
# On branch protractor-docs                                                 
# Changes not staged for commit:                                            
#   (use "git add <file>..." to update what will be committed)              
#   (use "git checkout -- <file>..." to discard changes in working directory)
#                                                                           
# modified:   config/config.json                                            
# modified:   config/index.json                                             
#                                                                           
no changes added to commit (use "git add" and/or "git commit -a")           

$ git diff                                                                  
diff --git a/config/config.json b/config/config.json                        
index 97afe06..95c7bc5 100755                                               
--- a/config/config.json                                                    
+++ b/config/config.json                                                    
@@ -3,6 +3,6 @@                                                             
   "remoteAutodocUrl": "https://raw.githubusercontent.com/dthree/wat/master/autodocs/",
   "remoteConfigUrl": "https://raw.githubusercontent.com/dthree/wat/master/config/",
   "remoteArchiveUrl": "https://api.github.com/repos/dthree/wat/tarball",   
-  "docIndexLastWrite": "2015-10-15T17:58:37.969Z",                         
-  "docIndexSize": 2527                                                     
+  "docIndexLastWrite": "2015-10-20T16:53:08.701Z",                         
+  "docIndexSize": 2700                                                     
 }                                                                          
\ No newline at end of file                                                 
diff --git a/config/index.json b/config/index.json                          
index 9b127ea..892d77c 100755                                               
--- a/config/index.json                                                     
+++ b/config/index.json                                                        
@@ -1 +1 @@                                                                    
-{"js":{"test":{"testify":{"__basic":363,"__type":"static","__class":"property"},"__class":"object"},"object":{"assign":{"__detail":3159,"__type":"static","__basic":561,"__class":"method"},"create":{"__detail":1577,"__type":"static","__basic":885,"__class":"method"}
\ No newline at end of file                                                    
+{"protractor":{"element":{"index":{"__basic":248,"__type":"static"},"all":{"index":{"__basic":300,"__type":"static"},"__class":"method"},"__class":"method"},"__class":"lib"},"js":{"test":{"testify":{"__basic":363,"__type":"static","__class":"property"},"__class":"o
\ No newline at end of file     

(copied from terminal, diff is truncated)

[dthree]

+{"protractor":{"element":{"index":{"__basic":248,"__type":"static"},"all":{"index":{"__basic":300,"__type":"static"},"__class":"method"},"__class":"method"},"__class":"lib"},"js":{"test":{"testify":{"__basic":363,"__type":"static","__class":"property"},"__class":"o

That's the index, correctly written.

[defel]

Ok, it means the current index is fetched from github? Not a bad idea, so the users does not have to update the client on them side all the time. Would be nice to have an option to use the local index then :)

Thanks for looking on it.

[dthree]

In a nutshell (I hope this makes sense):

You have a REMOTE index (github.com/dthree/wat),
You have a STATIC index (your cloned index when you npm install wat),
You have a TEMP index, in temp files so non-sudo users can always write.

1. wat index copies the remote index, and files it to temp.
2. When using wat, you always read the temp index.
3. gulp index writes to static, which you then push to remote.

---

You're right, I need to make a use static command or something for development.

---

And yeah, Wat is always checking and auto-updating the index, so it never goes out of date.

[dthree]

What do you think a good command would be?

Maybe:

$ wat dev
You are now in development mode, and can see your local document changes.
?

[defel]

Yes, I think this makes it clear and allows me to hack locally until I think the docs are ready to push.

Am 20. Oktober 2015 19:03:16 MESZ, schrieb dc [email protected]:

What do you think a good command would be?

Maybe:

$ wat dev
You are now in development mode, and can see your local document
changes.
?

---

Reply to this email directly or view it on GitHub:
#31 (comment)

Diese Nachricht wurde von meinem Android-Mobiltelefon mit K-9 Mail gesendet.

[dthree]

Great!

---

Okay this is done. Scrap gulp altogether. Just run node dev or node ./bin/index.js dev, and this will put you into a special dev mode. In this, the index command will built to and be based on the static files.

So, edit files, and then node dev to get into the special Wat mode, and then index to update and view your changes. You can even keep Wat open and keep doing index to see the changes.

[defel]

Sorry for my late reply. Had a chance to test this feature now and it works perfectly!

Just a little note:

When I add the docs locally, and reindex, I get the following errors:

? index

  Successfully updated index.

  3 documents are queued for updating.

  Sucessfully rebuilt index.

? Error fetching update for https://raw.githubusercontent.com/dthree/wat/master/docs/protractor/element/index.md: Not Found
Error fetching update for https://raw.githubusercontent.com/dthree/wat/master/docs/protractor/element/all/clone.md: Not Found
Error fetching update for https://raw.githubusercontent.com/dthree/wat/master/docs/protractor/element/all/index.md: Not Found

It works, but maybe the fetch is unnecessary for local docs in dev-mode?

[dthree]

Haha - whoops. Yeah, let me turn off that part. Shouldn't cause you trouble, but it isn't necessary.