search

gabrielcsapo / node-git-server

🎡 A configurable git server written in Node.js
https://gabrielcsapo.github.io/node-git-server
MIT License
253 stars 73 forks source link

Docs? #17

Closed OmgImAlexis closed 6 years ago

OmgImAlexis commented 7 years ago

I noticed there's a docs directory but no links to it.

gabrielcsapo commented 6 years ago

docs is located here http://www.gabrielcsapo.com/node-git-server/

gabrielcsapo commented 6 years ago

The page needs to be updated, going to update it later today with http://www.gabrielcsapo.com/tryitout/ so that it is a little more put together.

gabrielcsapo commented 6 years ago

I updated the docs in this commit https://github.com/gabrielcsapo/node-git-server/commit/3a1ebb29c895f7eb9e3e2e52f22875b0c4f2be09.

OmgImAlexis commented 6 years ago

@gabrielcsapo Glad to see the link added but the docs are still really sparse and missing key information such as what fields the first param actually returns.

For example with repos.on('push', function (push) { ... } what should push return? All I can see from the docs is that it's a http duplex object with at least three fields push.repo push.commit push.branch but that's it. When looking at the docs link to http-duplex I noticed that's also a dead end as it now points to a 404.

Should I open a new issue for this?

gabrielcsapo commented 6 years ago

@OmgImAlexis would you be interested in helping me find the information missing and updating it accordingly?

gabrielcsapo commented 6 years ago

@OmgImAlexis fixed the link problem here https://github.com/gabrielcsapo/node-git-server/commit/df8d7fea451e6a1ab7897467d5e3694e02f0851a.

gabrielcsapo commented 6 years ago

@echopoint do you have any pointers for how the docs can be improved?

echopoint commented 6 years ago

I haven't actually read the docs yet. ;) I'll take a look and see what I can come up with. I've been referring to the code and dissecting it because I do like the project and am working on an interface for it.. I abhor gitlab, so this was very welcome.

gabrielcsapo commented 6 years ago

🙌🏻 You rock, if you are working on an interface I would love to help with it!

On Sun, Nov 5, 2017 at 12:01 PM echopoint notifications@github.com wrote:

I haven't actually read the docs yet. ;) I'll take a look and see what I can come up with. I've been referring to the code and dissecting it because I do like the project and am working on an interface for it.. I abhor gitlab, so this was very welcome.

  1. Nov 2017 21:50 by notifications@github.com:

@echopoint> do you have any pointers for how the docs can be improved?

— You are receiving this because you were mentioned. Reply to this email directly, > view it on GitHub> , or > mute the thread> .

— You are receiving this because you modified the open/close state.

Reply to this email directly, view it on GitHub https://github.com/gabrielcsapo/node-git-server/issues/17#issuecomment-342009421, or mute the thread https://github.com/notifications/unsubscribe-auth/ABxNW8b6gBJg-c_eyDkmqPCzIlmleluOks5szjAxgaJpZM4PztOL .

echopoint commented 6 years ago

Ok. So now that HttpDuplex is in, I can add a little more doc to further explain it. Especially with the slight requirement of requiring newing the object instead of calling the function directly and it's destroy function, properties and methods that affect input / output.

Service needs some fleshing out for sure. Describing it's purpose and scope of function so we can keep it as trim as possible. The problem with these kinds of projects is they are geared towards those who have worked with the bowels of the source control or want to learn how something like that can work or does work and by definition aren't as user friendly or consumable as some may like. I think as long as we stay on top of the documentation the issue will sort itself out fairly quickly.

The docs are a little better now, though I'm sure more will come to me once I delve a little further into an interface. Since then I'm sure it will have touched every part of the server functionality and probably require some extension to it.

@OmgImAlexis pointed out the actual issue in the docs as it stands for the most part.. with it just being a little spare on functional description.

gabrielcsapo commented 6 years ago

@echopoint okay I can start commenting more of the core code pieces using jsdoc and inline comments.

As per the functional descriptions should it have a more in depth how to use section? I will send more time tommorow after work looking at what I can improve and submit a PR that both @echopoint and @OmgImAlexis can review if that works?

echopoint commented 6 years ago

Sure, I'm all for it. There could be a how to / tutorials section that could cover some basics and we can expand it from there as we go.