Swagger Doc and UI support (Was: Documentation to the official online site svn?)

[Woonsan Ko <wo...@apache.org>]

Hi Daewon, Do Yung and/or anyone interested in,

I've just submitted a PR which has the swagger UI support with the
default swagger document, initially for admin services:
- https://github.com/apache/incubator-s2graph/pull/197

I think Swagger UI with the default swagger doc for the APIs will make
it easier for many devs.
Could you please review it?

I figured out how to add /api-docs route there, but feel free to
correct it if I didn't follow any (Scala or Akka) best practices. ;-)

As described in the PR description, the following operations work fine
with the examples:
- /admin/createService, /admin/createLabel, /admin/addIndex,
/admin/getLabel/{name}

But, the following returns 404, for some reason which I can't figure out now:
- /admin/deleteLabel/{name}, /admin/addProp/{name}, /admin/createServiceColumn

Kind regards,

Woonsan

On Thu, Mar 28, 2019 at 9:45 AM Woonsan Ko <wo...@apache.org> wrote:
>
> On Thu, Mar 28, 2019 at 9:19 AM DO YUNG YOON <sh...@gmail.com> wrote:
> >
> > +1 for 'running' examples and would be happy to help if there is anything I
> > can help with.
> >
> > Also while I was going through the documentation to check if it is correct,
> > I found it is a bit tedious to copy payload on the doc to rest client(such
> > as postman).
> > I wish there was a documentation tool integration, such as swagger, which
> > also provides specs and UI to try each endpoint with examples.
> > I think integration with documentation tools is good for not only for users
> > but also developers who set up local development environments and fix code
> > and testing.
> >
> > Any thoughts?
>
> +1
> Great idea!
> If we provide a swagger UI (e.g, http://localhost:8000/api-docs), it
> will really boost developers understanding!
> We can probably include swagger UI under the /api-docs endpoint with a
> swagger.{json|yaml} file. I'm not accustomed to the scala web
> framework, but if someone expose a simple index.html under the
> /api-docs, then I can contribute or help create a pull request to
> enable swagger UI.
>
> Cheers,
>
> Woonsan
>
> >
> >
> > On Thu, Mar 28, 2019 at 10:05 PM Woonsan Ko <wo...@apache.org> wrote:
> >
> > > Wow, this is great!!!
> > > Thank you very much.
> > >
> > > As a side note, I'll try to follow the documentation to implement
> > > something simple -- by using S2Graph of course -- such as "Related
> > > articles" or "Related products" which are really popular use cases in
> > > most websites nowadays, but it's hard to implement actually in an
> > > automated way based on users' behaviors.
> > > If we have simple 'running' examples somewhere for normal web
> > > developers, I think it would help people adopt this project and
> > > solutions.
> > >
> > > Cheers,
> > >
> > > Woonsan
> > >
> > > On Thu, Mar 28, 2019 at 8:02 AM DO YUNG YOON <sh...@gmail.com> wrote:
> > > >
> > > > Hi Woonsan, Sorry for being late.
> > > >
> > > > I followed the instructions and the changes are now pushed to svn.
> > > >
> > > > Here is the updates
> > > >
> > > > - svn: https://svn.apache.org/repos/asf/incubator/s2graph/site (revision
> > > > 1856470)
> > > > - doc link on incubator site: *
> > > https://s2graph.apache.org/docs/index.html
> > > > <https://s2graph.apache.org/docs/index.html>*
> > > >
> > > > Please check the updates and feel free to comment
> > > >
> > > >
> > > > On Tue, Mar 5, 2019 at 11:10 PM Woonsan Ko <wo...@apache.org> wrote:
> > > >
> > > > > Thanks a lot, Do Yung, as always!
> > > > > Please tell me if there's anything I can help with.
> > > > >
> > > > > Cheers,
> > > > >
> > > > > Woonsan
> > > > >
> > > > > On Tue, Mar 5, 2019 at 12:12 AM DO YUNG YOON <sh...@gmail.com> wrote:
> > > > > >
> > > > > > Hi Woonsan.
> > > > > >
> > > > > > I agree with your suggestion, and I am volunteering for this.
> > > > > > Let me try working on this on weekends then I will share any
> > > > > > questions/updates.
> > > > > >
> > > > > > Thanks for your suggestion.
> > > > > >
> > > > > >
> > > > > > On Tue, Mar 5, 2019 at 11:27 AM Woonsan Ko <wo...@apache.org>
> > > wrote:
> > > > > >
> > > > > > > Hi folks,
> > > > > > >
> > > > > > > At the moment, the "Docs" link at the top menu bar [1] is linked
> > > to a
> > > > > > > non-ASF URL [2].
> > > > > > > I don't think we can keep the non-ASF pages there in the future.
> > > > > > > Furthermore, the documentation there is outdated from the
> > > > > > > documentation source at doc/.
> > > > > > >
> > > > > > > Our official documentation repository is the SVN [3], as of [4].
> > > > > > >
> > > > > > > Therefore, I'd like to propose the following:
> > > > > > > 1. Initially one of the committers should generate the site html
> > > from
> > > > > > > the doc/ in git source repo, following the instruction in
> > > > > > > doc/readme.md, until `make html`, which generates all the html and
> > > > > > > other static resource files at docs/build/html/. (I've just tested
> > > and
> > > > > > > it works fine.)
> > > > > > >    And, the generated files at docs/build/html/** should be
> > > committed
> > > > > > > to a new directory, "docs", in [3].
> > > > > > > 2. Change the "Docs" menu link to "docs/index.html" from the
> > > external
> > > > > link.
> > > > > > > 3. From now on, whenever committers update documentation, once in a
> > > > > > > while, do the step 1 and 2 periodically, to synchronize the online
> > > > > > > site with the documentation source.
> > > > > > >
> > > > > > > When we really want to expand the community during the incubation
> > > > > > > period, the online documentation is really crucial: new comers
> > > start
> > > > > > > from there...
> > > > > > >
> > > > > > > Any thoughts?
> > > > > > > If this sounds okay, any volunteers?
> > > > > > >
> > > > > > > Regards,
> > > > > > >
> > > > > > > Woonsan
> > > > > > >
> > > > > > > [1] http://s2graph.incubator.apache.org/
> > > > > > > [2] https://steamshon.gitbooks.io/s2graph-book/content/
> > > > > > > [3] http://svn.apache.org/repos/asf/incubator/s2graph/site/
> > > > > > > [4] https://issues.apache.org/jira/browse/INFRA-11806
> > > > > > >
> > > > >
> > >

Re: Swagger Doc and UI support (Was: Documentation to the official online site svn?)

[Woonsan Ko <wo...@apache.org>]

Hi Do Yung,

I see your point. Native support in Scala + Akka is better than manual
edits, of course.
There seems to be many more different libraries at the moment in Scala
ecosystem than Java's, like this one too:
- https://github.com/swagger-akka-http/swagger-akka-http

I'm not yet experienced much in Scala web application framework world,
so I can't really judge them. ;-) So, I'm open to you guys' opinions
and preferences.
What do others think?

Regards,

Woonsan

On Wed, May 1, 2019 at 4:31 AM DO YUNG YOON <sh...@gmail.com> wrote:
>
> Hi Woonsan.
>
> Sorry for the late response. It took me for a while to figure out what
> would be a nice way for working with OpenAPI document spec.
>
> I agree with your two cents, especially the importance of generating rest
> API reference through the right tool.
>
> Here is the tools I played with a little bit.
>
> - tapir: https://github.com/softwaremill/tapir
> - endpoints: http://julienrf.github.io/endpoints/index.html
>
> Personally, I prefer tapir, but it seems like it does not provide scala
> 2.11 available on maven central. I spent few days to upgrade scala version
> from 2.11 to 2.12, but realize it is not that easy(we may need to open up a
> separate discussion how we are going to upgrade scala version to 2.12).
>
> so just played with endpoints at this point and just sharing it with you to
> check if we are doing the right thing.
>
> here is how to test this PR(
> https://github.com/woonsan/incubator-s2graph/pull/1)
>
> 1. setup docker image on local for hbase.
>
> cd dev_support; docker-compose up graph_hbase
>
> 2. run akka http server in dev environment.
>
> sbt 'project s2http' '~reStart'
>
> 3. check the specs that generated by documentation server/spec.
>
> http://localhost:8000/api-docs/documentation.json
>
> 4. check the AdminEndpoints
>
> this is where our admin specs will reside on.
> I added few more specs for listing service/label/serviceColumns etc to
> validate if they are working.
>
> ex)
> - localhost:8000/admin/listServices
> - localhost:8000/admin/listLabels
> - localhost:8000/admin/listServiceColumns/s2graph
>
> IMAO, The nice thing about the above two libraries is that it separates the
> implementation and spec but still validate it on compile time, which I
> prefer over the annotation approach.
> I think it takes some time to get used to it for the first time, then after
> struggling, the library shine and basically, help us to synchronize API and
> doc so worth it.
>
> Please review and give any comments.
>
> On Wed, Apr 10, 2019 at 8:24 AM Woonsan Ko <wo...@apache.org> wrote:
>
> > On Mon, Apr 8, 2019 at 6:58 PM Woonsan Ko <wo...@apache.org> wrote:
> > >
> > > Hi Daewon, Do Yung and/or anyone interested in,
> > >
> > > I've just submitted a PR which has the swagger UI support with the
> > > default swagger document, initially for admin services:
> > > - https://github.com/apache/incubator-s2graph/pull/197
> > >
> > > I think Swagger UI with the default swagger doc for the APIs will make
> > > it easier for many devs.
> > > Could you please review it?
> > >
> > > I figured out how to add /api-docs route there, but feel free to
> > > correct it if I didn't follow any (Scala or Akka) best practices. ;-)
> > >
> > > As described in the PR description, the following operations work fine
> > > with the examples:
> > > - /admin/createService, /admin/createLabel, /admin/addIndex,
> > > /admin/getLabel/{name}
> > >
> > > But, the following returns 404, for some reason which I can't figure out
> > now:
> > > - /admin/deleteLabel/{name}, /admin/addProp/{name},
> > /admin/createServiceColumn
> >
> > I've pushed more and now those three are working fine.
> > I've noticed that `/admin/deleteLabel/{name}` in documentation was
> > changed to `/admin/deleteLabelReally/{name}` in code:
> > -
> > https://github.com/apache/incubator-s2graph/blob/master/s2http/src/main/scala/org/apache/s2graph/http/S2GraphAdminRoute.scala#L226
> >
> > There seems to be many in code outdating the documentation. For
> > example, there are many undocumented operations too. e.g. renameLabel,
> > copyLabel, swapLabel, etc.
> >
> > My two cents:
> > If you folks like the OpenAPI (swagger) document and its UI, then I'd
> > like to suggest you should keep the swagger doc as the single source
> > of truth for internal/external developers who are using the APIs,
> > always keeping it synchronized with the code. So, for example, if
> > someone makes changes in the REST APIs, it must be affected in the
> > OpenAPI (swagger) doc, too.
> > And, consider generating rest api reference documentation through a
> > tool like [1], and include or link those from the online
> > documentation.
> > Then you can minimize the risk of mismatch and outdated API references
> > and confusing developers who want to use it.
> >
> > Regards,
> >
> > Woonsan
> >
> > [1]
> > https://github.com/swagger-api/swagger-codegen#generating-static-html-api-documentation
> >
> > >
> > > Kind regards,
> > >
> > > Woonsan
> > >
> > > On Thu, Mar 28, 2019 at 9:45 AM Woonsan Ko <wo...@apache.org> wrote:
> > > >
> > > > On Thu, Mar 28, 2019 at 9:19 AM DO YUNG YOON <sh...@gmail.com> wrote:
> > > > >
> > > > > +1 for 'running' examples and would be happy to help if there is
> > anything I
> > > > > can help with.
> > > > >
> > > > > Also while I was going through the documentation to check if it is
> > correct,
> > > > > I found it is a bit tedious to copy payload on the doc to rest
> > client(such
> > > > > as postman).
> > > > > I wish there was a documentation tool integration, such as swagger,
> > which
> > > > > also provides specs and UI to try each endpoint with examples.
> > > > > I think integration with documentation tools is good for not only
> > for users
> > > > > but also developers who set up local development environments and
> > fix code
> > > > > and testing.
> > > > >
> > > > > Any thoughts?
> > > >
> > > > +1
> > > > Great idea!
> > > > If we provide a swagger UI (e.g, http://localhost:8000/api-docs), it
> > > > will really boost developers understanding!
> > > > We can probably include swagger UI under the /api-docs endpoint with a
> > > > swagger.{json|yaml} file. I'm not accustomed to the scala web
> > > > framework, but if someone expose a simple index.html under the
> > > > /api-docs, then I can contribute or help create a pull request to
> > > > enable swagger UI.
> > > >
> > > > Cheers,
> > > >
> > > > Woonsan
> > > >
> > > > >
> > > > >
> > > > > On Thu, Mar 28, 2019 at 10:05 PM Woonsan Ko <wo...@apache.org>
> > wrote:
> > > > >
> > > > > > Wow, this is great!!!
> > > > > > Thank you very much.
> > > > > >
> > > > > > As a side note, I'll try to follow the documentation to implement
> > > > > > something simple -- by using S2Graph of course -- such as "Related
> > > > > > articles" or "Related products" which are really popular use cases
> > in
> > > > > > most websites nowadays, but it's hard to implement actually in an
> > > > > > automated way based on users' behaviors.
> > > > > > If we have simple 'running' examples somewhere for normal web
> > > > > > developers, I think it would help people adopt this project and
> > > > > > solutions.
> > > > > >
> > > > > > Cheers,
> > > > > >
> > > > > > Woonsan
> > > > > >
> > > > > > On Thu, Mar 28, 2019 at 8:02 AM DO YUNG YOON <sh...@gmail.com>
> > wrote:
> > > > > > >
> > > > > > > Hi Woonsan, Sorry for being late.
> > > > > > >
> > > > > > > I followed the instructions and the changes are now pushed to
> > svn.
> > > > > > >
> > > > > > > Here is the updates
> > > > > > >
> > > > > > > - svn: https://svn.apache.org/repos/asf/incubator/s2graph/site
> > (revision
> > > > > > > 1856470)
> > > > > > > - doc link on incubator site: *
> > > > > > https://s2graph.apache.org/docs/index.html
> > > > > > > <https://s2graph.apache.org/docs/index.html>*
> > > > > > >
> > > > > > > Please check the updates and feel free to comment
> > > > > > >
> > > > > > >
> > > > > > > On Tue, Mar 5, 2019 at 11:10 PM Woonsan Ko <wo...@apache.org>
> > wrote:
> > > > > > >
> > > > > > > > Thanks a lot, Do Yung, as always!
> > > > > > > > Please tell me if there's anything I can help with.
> > > > > > > >
> > > > > > > > Cheers,
> > > > > > > >
> > > > > > > > Woonsan
> > > > > > > >
> > > > > > > > On Tue, Mar 5, 2019 at 12:12 AM DO YUNG YOON <sh...@gmail.com>
> > wrote:
> > > > > > > > >
> > > > > > > > > Hi Woonsan.
> > > > > > > > >
> > > > > > > > > I agree with your suggestion, and I am volunteering for this.
> > > > > > > > > Let me try working on this on weekends then I will share any
> > > > > > > > > questions/updates.
> > > > > > > > >
> > > > > > > > > Thanks for your suggestion.
> > > > > > > > >
> > > > > > > > >
> > > > > > > > > On Tue, Mar 5, 2019 at 11:27 AM Woonsan Ko <
> > woonsan@apache.org>
> > > > > > wrote:
> > > > > > > > >
> > > > > > > > > > Hi folks,
> > > > > > > > > >
> > > > > > > > > > At the moment, the "Docs" link at the top menu bar [1] is
> > linked
> > > > > > to a
> > > > > > > > > > non-ASF URL [2].
> > > > > > > > > > I don't think we can keep the non-ASF pages there in the
> > future.
> > > > > > > > > > Furthermore, the documentation there is outdated from the
> > > > > > > > > > documentation source at doc/.
> > > > > > > > > >
> > > > > > > > > > Our official documentation repository is the SVN [3], as
> > of [4].
> > > > > > > > > >
> > > > > > > > > > Therefore, I'd like to propose the following:
> > > > > > > > > > 1. Initially one of the committers should generate the
> > site html
> > > > > > from
> > > > > > > > > > the doc/ in git source repo, following the instruction in
> > > > > > > > > > doc/readme.md, until `make html`, which generates all the
> > html and
> > > > > > > > > > other static resource files at docs/build/html/. (I've
> > just tested
> > > > > > and
> > > > > > > > > > it works fine.)
> > > > > > > > > >    And, the generated files at docs/build/html/** should be
> > > > > > committed
> > > > > > > > > > to a new directory, "docs", in [3].
> > > > > > > > > > 2. Change the "Docs" menu link to "docs/index.html" from
> > the
> > > > > > external
> > > > > > > > link.
> > > > > > > > > > 3. From now on, whenever committers update documentation,
> > once in a
> > > > > > > > > > while, do the step 1 and 2 periodically, to synchronize
> > the online
> > > > > > > > > > site with the documentation source.
> > > > > > > > > >
> > > > > > > > > > When we really want to expand the community during the
> > incubation
> > > > > > > > > > period, the online documentation is really crucial: new
> > comers
> > > > > > start
> > > > > > > > > > from there...
> > > > > > > > > >
> > > > > > > > > > Any thoughts?
> > > > > > > > > > If this sounds okay, any volunteers?
> > > > > > > > > >
> > > > > > > > > > Regards,
> > > > > > > > > >
> > > > > > > > > > Woonsan
> > > > > > > > > >
> > > > > > > > > > [1] http://s2graph.incubator.apache.org/
> > > > > > > > > > [2] https://steamshon.gitbooks.io/s2graph-book/content/
> > > > > > > > > > [3]
> > http://svn.apache.org/repos/asf/incubator/s2graph/site/
> > > > > > > > > > [4] https://issues.apache.org/jira/browse/INFRA-11806
> > > > > > > > > >
> > > > > > > >
> > > > > >
> >

Re: Swagger Doc and UI support (Was: Documentation to the official online site svn?)

[DO YUNG YOON <sh...@gmail.com>]

Hi Woonsan.

Sorry for the late response. It took me for a while to figure out what
would be a nice way for working with OpenAPI document spec.

I agree with your two cents, especially the importance of generating rest
API reference through the right tool.

Here is the tools I played with a little bit.

- tapir: https://github.com/softwaremill/tapir
- endpoints: http://julienrf.github.io/endpoints/index.html

Personally, I prefer tapir, but it seems like it does not provide scala
2.11 available on maven central. I spent few days to upgrade scala version
from 2.11 to 2.12, but realize it is not that easy(we may need to open up a
separate discussion how we are going to upgrade scala version to 2.12).

so just played with endpoints at this point and just sharing it with you to
check if we are doing the right thing.

here is how to test this PR(
https://github.com/woonsan/incubator-s2graph/pull/1)

1. setup docker image on local for hbase.

cd dev_support; docker-compose up graph_hbase

2. run akka http server in dev environment.

sbt 'project s2http' '~reStart'

3. check the specs that generated by documentation server/spec.

http://localhost:8000/api-docs/documentation.json

4. check the AdminEndpoints

this is where our admin specs will reside on.
I added few more specs for listing service/label/serviceColumns etc to
validate if they are working.

ex)
- localhost:8000/admin/listServices
- localhost:8000/admin/listLabels
- localhost:8000/admin/listServiceColumns/s2graph

IMAO, The nice thing about the above two libraries is that it separates the
implementation and spec but still validate it on compile time, which I
prefer over the annotation approach.
I think it takes some time to get used to it for the first time, then after
struggling, the library shine and basically, help us to synchronize API and
doc so worth it.

Please review and give any comments.

On Wed, Apr 10, 2019 at 8:24 AM Woonsan Ko <wo...@apache.org> wrote:

> On Mon, Apr 8, 2019 at 6:58 PM Woonsan Ko <wo...@apache.org> wrote:
> >
> > Hi Daewon, Do Yung and/or anyone interested in,
> >
> > I've just submitted a PR which has the swagger UI support with the
> > default swagger document, initially for admin services:
> > - https://github.com/apache/incubator-s2graph/pull/197
> >
> > I think Swagger UI with the default swagger doc for the APIs will make
> > it easier for many devs.
> > Could you please review it?
> >
> > I figured out how to add /api-docs route there, but feel free to
> > correct it if I didn't follow any (Scala or Akka) best practices. ;-)
> >
> > As described in the PR description, the following operations work fine
> > with the examples:
> > - /admin/createService, /admin/createLabel, /admin/addIndex,
> > /admin/getLabel/{name}
> >
> > But, the following returns 404, for some reason which I can't figure out
> now:
> > - /admin/deleteLabel/{name}, /admin/addProp/{name},
> /admin/createServiceColumn
>
> I've pushed more and now those three are working fine.
> I've noticed that `/admin/deleteLabel/{name}` in documentation was
> changed to `/admin/deleteLabelReally/{name}` in code:
> -
> https://github.com/apache/incubator-s2graph/blob/master/s2http/src/main/scala/org/apache/s2graph/http/S2GraphAdminRoute.scala#L226
>
> There seems to be many in code outdating the documentation. For
> example, there are many undocumented operations too. e.g. renameLabel,
> copyLabel, swapLabel, etc.
>
> My two cents:
> If you folks like the OpenAPI (swagger) document and its UI, then I'd
> like to suggest you should keep the swagger doc as the single source
> of truth for internal/external developers who are using the APIs,
> always keeping it synchronized with the code. So, for example, if
> someone makes changes in the REST APIs, it must be affected in the
> OpenAPI (swagger) doc, too.
> And, consider generating rest api reference documentation through a
> tool like [1], and include or link those from the online
> documentation.
> Then you can minimize the risk of mismatch and outdated API references
> and confusing developers who want to use it.
>
> Regards,
>
> Woonsan
>
> [1]
> https://github.com/swagger-api/swagger-codegen#generating-static-html-api-documentation
>
> >
> > Kind regards,
> >
> > Woonsan
> >
> > On Thu, Mar 28, 2019 at 9:45 AM Woonsan Ko <wo...@apache.org> wrote:
> > >
> > > On Thu, Mar 28, 2019 at 9:19 AM DO YUNG YOON <sh...@gmail.com> wrote:
> > > >
> > > > +1 for 'running' examples and would be happy to help if there is
> anything I
> > > > can help with.
> > > >
> > > > Also while I was going through the documentation to check if it is
> correct,
> > > > I found it is a bit tedious to copy payload on the doc to rest
> client(such
> > > > as postman).
> > > > I wish there was a documentation tool integration, such as swagger,
> which
> > > > also provides specs and UI to try each endpoint with examples.
> > > > I think integration with documentation tools is good for not only
> for users
> > > > but also developers who set up local development environments and
> fix code
> > > > and testing.
> > > >
> > > > Any thoughts?
> > >
> > > +1
> > > Great idea!
> > > If we provide a swagger UI (e.g, http://localhost:8000/api-docs), it
> > > will really boost developers understanding!
> > > We can probably include swagger UI under the /api-docs endpoint with a
> > > swagger.{json|yaml} file. I'm not accustomed to the scala web
> > > framework, but if someone expose a simple index.html under the
> > > /api-docs, then I can contribute or help create a pull request to
> > > enable swagger UI.
> > >
> > > Cheers,
> > >
> > > Woonsan
> > >
> > > >
> > > >
> > > > On Thu, Mar 28, 2019 at 10:05 PM Woonsan Ko <wo...@apache.org>
> wrote:
> > > >
> > > > > Wow, this is great!!!
> > > > > Thank you very much.
> > > > >
> > > > > As a side note, I'll try to follow the documentation to implement
> > > > > something simple -- by using S2Graph of course -- such as "Related
> > > > > articles" or "Related products" which are really popular use cases
> in
> > > > > most websites nowadays, but it's hard to implement actually in an
> > > > > automated way based on users' behaviors.
> > > > > If we have simple 'running' examples somewhere for normal web
> > > > > developers, I think it would help people adopt this project and
> > > > > solutions.
> > > > >
> > > > > Cheers,
> > > > >
> > > > > Woonsan
> > > > >
> > > > > On Thu, Mar 28, 2019 at 8:02 AM DO YUNG YOON <sh...@gmail.com>
> wrote:
> > > > > >
> > > > > > Hi Woonsan, Sorry for being late.
> > > > > >
> > > > > > I followed the instructions and the changes are now pushed to
> svn.
> > > > > >
> > > > > > Here is the updates
> > > > > >
> > > > > > - svn: https://svn.apache.org/repos/asf/incubator/s2graph/site
> (revision
> > > > > > 1856470)
> > > > > > - doc link on incubator site: *
> > > > > https://s2graph.apache.org/docs/index.html
> > > > > > <https://s2graph.apache.org/docs/index.html>*
> > > > > >
> > > > > > Please check the updates and feel free to comment
> > > > > >
> > > > > >
> > > > > > On Tue, Mar 5, 2019 at 11:10 PM Woonsan Ko <wo...@apache.org>
> wrote:
> > > > > >
> > > > > > > Thanks a lot, Do Yung, as always!
> > > > > > > Please tell me if there's anything I can help with.
> > > > > > >
> > > > > > > Cheers,
> > > > > > >
> > > > > > > Woonsan
> > > > > > >
> > > > > > > On Tue, Mar 5, 2019 at 12:12 AM DO YUNG YOON <sh...@gmail.com>
> wrote:
> > > > > > > >
> > > > > > > > Hi Woonsan.
> > > > > > > >
> > > > > > > > I agree with your suggestion, and I am volunteering for this.
> > > > > > > > Let me try working on this on weekends then I will share any
> > > > > > > > questions/updates.
> > > > > > > >
> > > > > > > > Thanks for your suggestion.
> > > > > > > >
> > > > > > > >
> > > > > > > > On Tue, Mar 5, 2019 at 11:27 AM Woonsan Ko <
> woonsan@apache.org>
> > > > > wrote:
> > > > > > > >
> > > > > > > > > Hi folks,
> > > > > > > > >
> > > > > > > > > At the moment, the "Docs" link at the top menu bar [1] is
> linked
> > > > > to a
> > > > > > > > > non-ASF URL [2].
> > > > > > > > > I don't think we can keep the non-ASF pages there in the
> future.
> > > > > > > > > Furthermore, the documentation there is outdated from the
> > > > > > > > > documentation source at doc/.
> > > > > > > > >
> > > > > > > > > Our official documentation repository is the SVN [3], as
> of [4].
> > > > > > > > >
> > > > > > > > > Therefore, I'd like to propose the following:
> > > > > > > > > 1. Initially one of the committers should generate the
> site html
> > > > > from
> > > > > > > > > the doc/ in git source repo, following the instruction in
> > > > > > > > > doc/readme.md, until `make html`, which generates all the
> html and
> > > > > > > > > other static resource files at docs/build/html/. (I've
> just tested
> > > > > and
> > > > > > > > > it works fine.)
> > > > > > > > >    And, the generated files at docs/build/html/** should be
> > > > > committed
> > > > > > > > > to a new directory, "docs", in [3].
> > > > > > > > > 2. Change the "Docs" menu link to "docs/index.html" from
> the
> > > > > external
> > > > > > > link.
> > > > > > > > > 3. From now on, whenever committers update documentation,
> once in a
> > > > > > > > > while, do the step 1 and 2 periodically, to synchronize
> the online
> > > > > > > > > site with the documentation source.
> > > > > > > > >
> > > > > > > > > When we really want to expand the community during the
> incubation
> > > > > > > > > period, the online documentation is really crucial: new
> comers
> > > > > start
> > > > > > > > > from there...
> > > > > > > > >
> > > > > > > > > Any thoughts?
> > > > > > > > > If this sounds okay, any volunteers?
> > > > > > > > >
> > > > > > > > > Regards,
> > > > > > > > >
> > > > > > > > > Woonsan
> > > > > > > > >
> > > > > > > > > [1] http://s2graph.incubator.apache.org/
> > > > > > > > > [2] https://steamshon.gitbooks.io/s2graph-book/content/
> > > > > > > > > [3]
> http://svn.apache.org/repos/asf/incubator/s2graph/site/
> > > > > > > > > [4] https://issues.apache.org/jira/browse/INFRA-11806
> > > > > > > > >
> > > > > > >
> > > > >
>

Re: Swagger Doc and UI support (Was: Documentation to the official online site svn?)

[Woonsan Ko <wo...@apache.org>]

On Mon, Apr 8, 2019 at 6:58 PM Woonsan Ko <wo...@apache.org> wrote:
>
> Hi Daewon, Do Yung and/or anyone interested in,
>
> I've just submitted a PR which has the swagger UI support with the
> default swagger document, initially for admin services:
> - https://github.com/apache/incubator-s2graph/pull/197
>
> I think Swagger UI with the default swagger doc for the APIs will make
> it easier for many devs.
> Could you please review it?
>
> I figured out how to add /api-docs route there, but feel free to
> correct it if I didn't follow any (Scala or Akka) best practices. ;-)
>
> As described in the PR description, the following operations work fine
> with the examples:
> - /admin/createService, /admin/createLabel, /admin/addIndex,
> /admin/getLabel/{name}
>
> But, the following returns 404, for some reason which I can't figure out now:
> - /admin/deleteLabel/{name}, /admin/addProp/{name}, /admin/createServiceColumn

I've pushed more and now those three are working fine.
I've noticed that `/admin/deleteLabel/{name}` in documentation was
changed to `/admin/deleteLabelReally/{name}` in code:
- https://github.com/apache/incubator-s2graph/blob/master/s2http/src/main/scala/org/apache/s2graph/http/S2GraphAdminRoute.scala#L226

There seems to be many in code outdating the documentation. For
example, there are many undocumented operations too. e.g. renameLabel,
copyLabel, swapLabel, etc.

My two cents:
If you folks like the OpenAPI (swagger) document and its UI, then I'd
like to suggest you should keep the swagger doc as the single source
of truth for internal/external developers who are using the APIs,
always keeping it synchronized with the code. So, for example, if
someone makes changes in the REST APIs, it must be affected in the
OpenAPI (swagger) doc, too.
And, consider generating rest api reference documentation through a
tool like [1], and include or link those from the online
documentation.
Then you can minimize the risk of mismatch and outdated API references
and confusing developers who want to use it.

Regards,

Woonsan

[1] https://github.com/swagger-api/swagger-codegen#generating-static-html-api-documentation

>
> Kind regards,
>
> Woonsan
>
> On Thu, Mar 28, 2019 at 9:45 AM Woonsan Ko <wo...@apache.org> wrote:
> >
> > On Thu, Mar 28, 2019 at 9:19 AM DO YUNG YOON <sh...@gmail.com> wrote:
> > >
> > > +1 for 'running' examples and would be happy to help if there is anything I
> > > can help with.
> > >
> > > Also while I was going through the documentation to check if it is correct,
> > > I found it is a bit tedious to copy payload on the doc to rest client(such
> > > as postman).
> > > I wish there was a documentation tool integration, such as swagger, which
> > > also provides specs and UI to try each endpoint with examples.
> > > I think integration with documentation tools is good for not only for users
> > > but also developers who set up local development environments and fix code
> > > and testing.
> > >
> > > Any thoughts?
> >
> > +1
> > Great idea!
> > If we provide a swagger UI (e.g, http://localhost:8000/api-docs), it
> > will really boost developers understanding!
> > We can probably include swagger UI under the /api-docs endpoint with a
> > swagger.{json|yaml} file. I'm not accustomed to the scala web
> > framework, but if someone expose a simple index.html under the
> > /api-docs, then I can contribute or help create a pull request to
> > enable swagger UI.
> >
> > Cheers,
> >
> > Woonsan
> >
> > >
> > >
> > > On Thu, Mar 28, 2019 at 10:05 PM Woonsan Ko <wo...@apache.org> wrote:
> > >
> > > > Wow, this is great!!!
> > > > Thank you very much.
> > > >
> > > > As a side note, I'll try to follow the documentation to implement
> > > > something simple -- by using S2Graph of course -- such as "Related
> > > > articles" or "Related products" which are really popular use cases in
> > > > most websites nowadays, but it's hard to implement actually in an
> > > > automated way based on users' behaviors.
> > > > If we have simple 'running' examples somewhere for normal web
> > > > developers, I think it would help people adopt this project and
> > > > solutions.
> > > >
> > > > Cheers,
> > > >
> > > > Woonsan
> > > >
> > > > On Thu, Mar 28, 2019 at 8:02 AM DO YUNG YOON <sh...@gmail.com> wrote:
> > > > >
> > > > > Hi Woonsan, Sorry for being late.
> > > > >
> > > > > I followed the instructions and the changes are now pushed to svn.
> > > > >
> > > > > Here is the updates
> > > > >
> > > > > - svn: https://svn.apache.org/repos/asf/incubator/s2graph/site (revision
> > > > > 1856470)
> > > > > - doc link on incubator site: *
> > > > https://s2graph.apache.org/docs/index.html
> > > > > <https://s2graph.apache.org/docs/index.html>*
> > > > >
> > > > > Please check the updates and feel free to comment
> > > > >
> > > > >
> > > > > On Tue, Mar 5, 2019 at 11:10 PM Woonsan Ko <wo...@apache.org> wrote:
> > > > >
> > > > > > Thanks a lot, Do Yung, as always!
> > > > > > Please tell me if there's anything I can help with.
> > > > > >
> > > > > > Cheers,
> > > > > >
> > > > > > Woonsan
> > > > > >
> > > > > > On Tue, Mar 5, 2019 at 12:12 AM DO YUNG YOON <sh...@gmail.com> wrote:
> > > > > > >
> > > > > > > Hi Woonsan.
> > > > > > >
> > > > > > > I agree with your suggestion, and I am volunteering for this.
> > > > > > > Let me try working on this on weekends then I will share any
> > > > > > > questions/updates.
> > > > > > >
> > > > > > > Thanks for your suggestion.
> > > > > > >
> > > > > > >
> > > > > > > On Tue, Mar 5, 2019 at 11:27 AM Woonsan Ko <wo...@apache.org>
> > > > wrote:
> > > > > > >
> > > > > > > > Hi folks,
> > > > > > > >
> > > > > > > > At the moment, the "Docs" link at the top menu bar [1] is linked
> > > > to a
> > > > > > > > non-ASF URL [2].
> > > > > > > > I don't think we can keep the non-ASF pages there in the future.
> > > > > > > > Furthermore, the documentation there is outdated from the
> > > > > > > > documentation source at doc/.
> > > > > > > >
> > > > > > > > Our official documentation repository is the SVN [3], as of [4].
> > > > > > > >
> > > > > > > > Therefore, I'd like to propose the following:
> > > > > > > > 1. Initially one of the committers should generate the site html
> > > > from
> > > > > > > > the doc/ in git source repo, following the instruction in
> > > > > > > > doc/readme.md, until `make html`, which generates all the html and
> > > > > > > > other static resource files at docs/build/html/. (I've just tested
> > > > and
> > > > > > > > it works fine.)
> > > > > > > >    And, the generated files at docs/build/html/** should be
> > > > committed
> > > > > > > > to a new directory, "docs", in [3].
> > > > > > > > 2. Change the "Docs" menu link to "docs/index.html" from the
> > > > external
> > > > > > link.
> > > > > > > > 3. From now on, whenever committers update documentation, once in a
> > > > > > > > while, do the step 1 and 2 periodically, to synchronize the online
> > > > > > > > site with the documentation source.
> > > > > > > >
> > > > > > > > When we really want to expand the community during the incubation
> > > > > > > > period, the online documentation is really crucial: new comers
> > > > start
> > > > > > > > from there...
> > > > > > > >
> > > > > > > > Any thoughts?
> > > > > > > > If this sounds okay, any volunteers?
> > > > > > > >
> > > > > > > > Regards,
> > > > > > > >
> > > > > > > > Woonsan
> > > > > > > >
> > > > > > > > [1] http://s2graph.incubator.apache.org/
> > > > > > > > [2] https://steamshon.gitbooks.io/s2graph-book/content/
> > > > > > > > [3] http://svn.apache.org/repos/asf/incubator/s2graph/site/
> > > > > > > > [4] https://issues.apache.org/jira/browse/INFRA-11806
> > > > > > > >
> > > > > >
> > > >

Re: Swagger Doc and UI support (Was: Documentation to the official online site svn?)

[Woonsan Ko <wo...@apache.org>]

Cool! Thank you sir!

Woonsan

On Tue, Apr 9, 2019 at 8:48 AM DO YUNG YOON <sh...@gmail.com> wrote:
>
> Hi Woonsan. Sorry for the late reply.
>
> I really appreciate getting involved and I would love to review it.
> I will read through the PR on this week, then ask any questions on this
> thread.
>
> Thanks for your contribution!
>
> On Tue, Apr 9, 2019 at 7:58 AM Woonsan Ko <wo...@apache.org> wrote:
>
> > Hi Daewon, Do Yung and/or anyone interested in,
> >
> > I've just submitted a PR which has the swagger UI support with the
> > default swagger document, initially for admin services:
> > - https://github.com/apache/incubator-s2graph/pull/197
> >
> > I think Swagger UI with the default swagger doc for the APIs will make
> > it easier for many devs.
> > Could you please review it?
> >
> > I figured out how to add /api-docs route there, but feel free to
> > correct it if I didn't follow any (Scala or Akka) best practices. ;-)
> >
> > As described in the PR description, the following operations work fine
> > with the examples:
> > - /admin/createService, /admin/createLabel, /admin/addIndex,
> > /admin/getLabel/{name}
> >
> > But, the following returns 404, for some reason which I can't figure out
> > now:
> > - /admin/deleteLabel/{name}, /admin/addProp/{name},
> > /admin/createServiceColumn
> >
> > Kind regards,
> >
> > Woonsan
> >
> > On Thu, Mar 28, 2019 at 9:45 AM Woonsan Ko <wo...@apache.org> wrote:
> > >
> > > On Thu, Mar 28, 2019 at 9:19 AM DO YUNG YOON <sh...@gmail.com> wrote:
> > > >
> > > > +1 for 'running' examples and would be happy to help if there is
> > anything I
> > > > can help with.
> > > >
> > > > Also while I was going through the documentation to check if it is
> > correct,
> > > > I found it is a bit tedious to copy payload on the doc to rest
> > client(such
> > > > as postman).
> > > > I wish there was a documentation tool integration, such as swagger,
> > which
> > > > also provides specs and UI to try each endpoint with examples.
> > > > I think integration with documentation tools is good for not only for
> > users
> > > > but also developers who set up local development environments and fix
> > code
> > > > and testing.
> > > >
> > > > Any thoughts?
> > >
> > > +1
> > > Great idea!
> > > If we provide a swagger UI (e.g, http://localhost:8000/api-docs), it
> > > will really boost developers understanding!
> > > We can probably include swagger UI under the /api-docs endpoint with a
> > > swagger.{json|yaml} file. I'm not accustomed to the scala web
> > > framework, but if someone expose a simple index.html under the
> > > /api-docs, then I can contribute or help create a pull request to
> > > enable swagger UI.
> > >
> > > Cheers,
> > >
> > > Woonsan
> > >
> > > >
> > > >
> > > > On Thu, Mar 28, 2019 at 10:05 PM Woonsan Ko <wo...@apache.org>
> > wrote:
> > > >
> > > > > Wow, this is great!!!
> > > > > Thank you very much.
> > > > >
> > > > > As a side note, I'll try to follow the documentation to implement
> > > > > something simple -- by using S2Graph of course -- such as "Related
> > > > > articles" or "Related products" which are really popular use cases in
> > > > > most websites nowadays, but it's hard to implement actually in an
> > > > > automated way based on users' behaviors.
> > > > > If we have simple 'running' examples somewhere for normal web
> > > > > developers, I think it would help people adopt this project and
> > > > > solutions.
> > > > >
> > > > > Cheers,
> > > > >
> > > > > Woonsan
> > > > >
> > > > > On Thu, Mar 28, 2019 at 8:02 AM DO YUNG YOON <sh...@gmail.com>
> > wrote:
> > > > > >
> > > > > > Hi Woonsan, Sorry for being late.
> > > > > >
> > > > > > I followed the instructions and the changes are now pushed to svn.
> > > > > >
> > > > > > Here is the updates
> > > > > >
> > > > > > - svn: https://svn.apache.org/repos/asf/incubator/s2graph/site
> > (revision
> > > > > > 1856470)
> > > > > > - doc link on incubator site: *
> > > > > https://s2graph.apache.org/docs/index.html
> > > > > > <https://s2graph.apache.org/docs/index.html>*
> > > > > >
> > > > > > Please check the updates and feel free to comment
> > > > > >
> > > > > >
> > > > > > On Tue, Mar 5, 2019 at 11:10 PM Woonsan Ko <wo...@apache.org>
> > wrote:
> > > > > >
> > > > > > > Thanks a lot, Do Yung, as always!
> > > > > > > Please tell me if there's anything I can help with.
> > > > > > >
> > > > > > > Cheers,
> > > > > > >
> > > > > > > Woonsan
> > > > > > >
> > > > > > > On Tue, Mar 5, 2019 at 12:12 AM DO YUNG YOON <sh...@gmail.com>
> > wrote:
> > > > > > > >
> > > > > > > > Hi Woonsan.
> > > > > > > >
> > > > > > > > I agree with your suggestion, and I am volunteering for this.
> > > > > > > > Let me try working on this on weekends then I will share any
> > > > > > > > questions/updates.
> > > > > > > >
> > > > > > > > Thanks for your suggestion.
> > > > > > > >
> > > > > > > >
> > > > > > > > On Tue, Mar 5, 2019 at 11:27 AM Woonsan Ko <woonsan@apache.org
> > >
> > > > > wrote:
> > > > > > > >
> > > > > > > > > Hi folks,
> > > > > > > > >
> > > > > > > > > At the moment, the "Docs" link at the top menu bar [1] is
> > linked
> > > > > to a
> > > > > > > > > non-ASF URL [2].
> > > > > > > > > I don't think we can keep the non-ASF pages there in the
> > future.
> > > > > > > > > Furthermore, the documentation there is outdated from the
> > > > > > > > > documentation source at doc/.
> > > > > > > > >
> > > > > > > > > Our official documentation repository is the SVN [3], as of
> > [4].
> > > > > > > > >
> > > > > > > > > Therefore, I'd like to propose the following:
> > > > > > > > > 1. Initially one of the committers should generate the site
> > html
> > > > > from
> > > > > > > > > the doc/ in git source repo, following the instruction in
> > > > > > > > > doc/readme.md, until `make html`, which generates all the
> > html and
> > > > > > > > > other static resource files at docs/build/html/. (I've just
> > tested
> > > > > and
> > > > > > > > > it works fine.)
> > > > > > > > >    And, the generated files at docs/build/html/** should be
> > > > > committed
> > > > > > > > > to a new directory, "docs", in [3].
> > > > > > > > > 2. Change the "Docs" menu link to "docs/index.html" from the
> > > > > external
> > > > > > > link.
> > > > > > > > > 3. From now on, whenever committers update documentation,
> > once in a
> > > > > > > > > while, do the step 1 and 2 periodically, to synchronize the
> > online
> > > > > > > > > site with the documentation source.
> > > > > > > > >
> > > > > > > > > When we really want to expand the community during the
> > incubation
> > > > > > > > > period, the online documentation is really crucial: new
> > comers
> > > > > start
> > > > > > > > > from there...
> > > > > > > > >
> > > > > > > > > Any thoughts?
> > > > > > > > > If this sounds okay, any volunteers?
> > > > > > > > >
> > > > > > > > > Regards,
> > > > > > > > >
> > > > > > > > > Woonsan
> > > > > > > > >
> > > > > > > > > [1] http://s2graph.incubator.apache.org/
> > > > > > > > > [2] https://steamshon.gitbooks.io/s2graph-book/content/
> > > > > > > > > [3] http://svn.apache.org/repos/asf/incubator/s2graph/site/
> > > > > > > > > [4] https://issues.apache.org/jira/browse/INFRA-11806
> > > > > > > > >
> > > > > > >
> > > > >
> >

Re: Swagger Doc and UI support (Was: Documentation to the official online site svn?)

[DO YUNG YOON <sh...@gmail.com>]

Hi Woonsan. Sorry for the late reply.

I really appreciate getting involved and I would love to review it.
I will read through the PR on this week, then ask any questions on this
thread.

Thanks for your contribution!

On Tue, Apr 9, 2019 at 7:58 AM Woonsan Ko <wo...@apache.org> wrote:

> Hi Daewon, Do Yung and/or anyone interested in,
>
> I've just submitted a PR which has the swagger UI support with the
> default swagger document, initially for admin services:
> - https://github.com/apache/incubator-s2graph/pull/197
>
> I think Swagger UI with the default swagger doc for the APIs will make
> it easier for many devs.
> Could you please review it?
>
> I figured out how to add /api-docs route there, but feel free to
> correct it if I didn't follow any (Scala or Akka) best practices. ;-)
>
> As described in the PR description, the following operations work fine
> with the examples:
> - /admin/createService, /admin/createLabel, /admin/addIndex,
> /admin/getLabel/{name}
>
> But, the following returns 404, for some reason which I can't figure out
> now:
> - /admin/deleteLabel/{name}, /admin/addProp/{name},
> /admin/createServiceColumn
>
> Kind regards,
>
> Woonsan
>
> On Thu, Mar 28, 2019 at 9:45 AM Woonsan Ko <wo...@apache.org> wrote:
> >
> > On Thu, Mar 28, 2019 at 9:19 AM DO YUNG YOON <sh...@gmail.com> wrote:
> > >
> > > +1 for 'running' examples and would be happy to help if there is
> anything I
> > > can help with.
> > >
> > > Also while I was going through the documentation to check if it is
> correct,
> > > I found it is a bit tedious to copy payload on the doc to rest
> client(such
> > > as postman).
> > > I wish there was a documentation tool integration, such as swagger,
> which
> > > also provides specs and UI to try each endpoint with examples.
> > > I think integration with documentation tools is good for not only for
> users
> > > but also developers who set up local development environments and fix
> code
> > > and testing.
> > >
> > > Any thoughts?
> >
> > +1
> > Great idea!
> > If we provide a swagger UI (e.g, http://localhost:8000/api-docs), it
> > will really boost developers understanding!
> > We can probably include swagger UI under the /api-docs endpoint with a
> > swagger.{json|yaml} file. I'm not accustomed to the scala web
> > framework, but if someone expose a simple index.html under the
> > /api-docs, then I can contribute or help create a pull request to
> > enable swagger UI.
> >
> > Cheers,
> >
> > Woonsan
> >
> > >
> > >
> > > On Thu, Mar 28, 2019 at 10:05 PM Woonsan Ko <wo...@apache.org>
> wrote:
> > >
> > > > Wow, this is great!!!
> > > > Thank you very much.
> > > >
> > > > As a side note, I'll try to follow the documentation to implement
> > > > something simple -- by using S2Graph of course -- such as "Related
> > > > articles" or "Related products" which are really popular use cases in
> > > > most websites nowadays, but it's hard to implement actually in an
> > > > automated way based on users' behaviors.
> > > > If we have simple 'running' examples somewhere for normal web
> > > > developers, I think it would help people adopt this project and
> > > > solutions.
> > > >
> > > > Cheers,
> > > >
> > > > Woonsan
> > > >
> > > > On Thu, Mar 28, 2019 at 8:02 AM DO YUNG YOON <sh...@gmail.com>
> wrote:
> > > > >
> > > > > Hi Woonsan, Sorry for being late.
> > > > >
> > > > > I followed the instructions and the changes are now pushed to svn.
> > > > >
> > > > > Here is the updates
> > > > >
> > > > > - svn: https://svn.apache.org/repos/asf/incubator/s2graph/site
> (revision
> > > > > 1856470)
> > > > > - doc link on incubator site: *
> > > > https://s2graph.apache.org/docs/index.html
> > > > > <https://s2graph.apache.org/docs/index.html>*
> > > > >
> > > > > Please check the updates and feel free to comment
> > > > >
> > > > >
> > > > > On Tue, Mar 5, 2019 at 11:10 PM Woonsan Ko <wo...@apache.org>
> wrote:
> > > > >
> > > > > > Thanks a lot, Do Yung, as always!
> > > > > > Please tell me if there's anything I can help with.
> > > > > >
> > > > > > Cheers,
> > > > > >
> > > > > > Woonsan
> > > > > >
> > > > > > On Tue, Mar 5, 2019 at 12:12 AM DO YUNG YOON <sh...@gmail.com>
> wrote:
> > > > > > >
> > > > > > > Hi Woonsan.
> > > > > > >
> > > > > > > I agree with your suggestion, and I am volunteering for this.
> > > > > > > Let me try working on this on weekends then I will share any
> > > > > > > questions/updates.
> > > > > > >
> > > > > > > Thanks for your suggestion.
> > > > > > >
> > > > > > >
> > > > > > > On Tue, Mar 5, 2019 at 11:27 AM Woonsan Ko <woonsan@apache.org
> >
> > > > wrote:
> > > > > > >
> > > > > > > > Hi folks,
> > > > > > > >
> > > > > > > > At the moment, the "Docs" link at the top menu bar [1] is
> linked
> > > > to a
> > > > > > > > non-ASF URL [2].
> > > > > > > > I don't think we can keep the non-ASF pages there in the
> future.
> > > > > > > > Furthermore, the documentation there is outdated from the
> > > > > > > > documentation source at doc/.
> > > > > > > >
> > > > > > > > Our official documentation repository is the SVN [3], as of
> [4].
> > > > > > > >
> > > > > > > > Therefore, I'd like to propose the following:
> > > > > > > > 1. Initially one of the committers should generate the site
> html
> > > > from
> > > > > > > > the doc/ in git source repo, following the instruction in
> > > > > > > > doc/readme.md, until `make html`, which generates all the
> html and
> > > > > > > > other static resource files at docs/build/html/. (I've just
> tested
> > > > and
> > > > > > > > it works fine.)
> > > > > > > >    And, the generated files at docs/build/html/** should be
> > > > committed
> > > > > > > > to a new directory, "docs", in [3].
> > > > > > > > 2. Change the "Docs" menu link to "docs/index.html" from the
> > > > external
> > > > > > link.
> > > > > > > > 3. From now on, whenever committers update documentation,
> once in a
> > > > > > > > while, do the step 1 and 2 periodically, to synchronize the
> online
> > > > > > > > site with the documentation source.
> > > > > > > >
> > > > > > > > When we really want to expand the community during the
> incubation
> > > > > > > > period, the online documentation is really crucial: new
> comers
> > > > start
> > > > > > > > from there...
> > > > > > > >
> > > > > > > > Any thoughts?
> > > > > > > > If this sounds okay, any volunteers?
> > > > > > > >
> > > > > > > > Regards,
> > > > > > > >
> > > > > > > > Woonsan
> > > > > > > >
> > > > > > > > [1] http://s2graph.incubator.apache.org/
> > > > > > > > [2] https://steamshon.gitbooks.io/s2graph-book/content/
> > > > > > > > [3] http://svn.apache.org/repos/asf/incubator/s2graph/site/
> > > > > > > > [4] https://issues.apache.org/jira/browse/INFRA-11806
> > > > > > > >
> > > > > >
> > > >
>