[Libstoragemgmt-devel] [RFC] Using git pages for libstoragemgmt documents

[Gris Ge]

Hi guys,

I just created an demo for libstoragemgmt documentation:
http://cathay4t.github.io/libstoragemgmt-doc/
# Just copy existing sf.net wiki files to github.

Features:
1. Use markdown file and git repo, codes:
https://github.com/cathay4t/libstoragemgmt-doc

2. It could integrate to upstream git repo with 'gh-pages' branch.
# We need discuss on "two repo vs one repo"
# Some document like 'known issues' might not link to code
# change(like SMI-S provider bugs). So I prefer to using
# separate git like 'libstoragemgmt-doc'.

3. Use GitHub Flavored Markdown.[1]

3. It could make a quit good front page for libstoragemgmt
project.
With some html/css coding care(the _layouts/default.html), of source.

Issues:

1. Cannot auto generate TOC(Table of Content).
https://github.com/isaacs/github/issues/215
Workaround:
manually generated table of contents
Check this page for demo:
http://cathay4t.github.io/libstoragemgmt-doc/doc/quick_user_guide

2. A lot TODO in markdown files. :)

3. My bad English. :(

I also intend to use markdown file to manually code down all C API and
Python API in human friendly way.

Any comments and suggestions.

[1]: https://help.github.com/articles/github-flavored-markdown/

[Tony Asleson]

Post by Gris Ge
Hi guys,
http://cathay4t.github.io/libstoragemgmt-doc/
# Just copy existing sf.net wiki files to github.

This looks pretty good!

Post by Gris Ge
https://github.com/cathay4t/libstoragemgmt-doc
2. It could integrate to upstream git repo with 'gh-pages' branch.
# We need discuss on "two repo vs one repo"
# Some document like 'known issues' might not link to code
# change(like SMI-S provider bugs). So I prefer to using
# separate git like 'libstoragemgmt-doc'.

Can you elaborate on this some more. I guess I'm not fully
understanding why you prefer 2 git repos to 1 with the documentation in
a branch and I'm not following the 'known issues' point.

Post by Gris Ge
3. Use GitHub Flavored Markdown.[1]
3. It could make a quit good front page for libstoragemgmt
project.
With some html/css coding care(the _layouts/default.html), of source.
1. Cannot auto generate TOC(Table of Content).
https://github.com/isaacs/github/issues/215
manually generated table of contents
http://cathay4t.github.io/libstoragemgmt-doc/doc/quick_user_guide

I believe if you use asciidoc markdown you can get a TOC, but then you
lose other functionality.

I stubbed out some wiki pages and I was actually thinking that instead
of using a TOC, if each topic was placed on it's own page a person could
use the sidebar instead of a TOC for navigation.

see: https://github.com/libstorage/libstoragemgmt/wiki

Post by Gris Ge
2. A lot TODO in markdown files. :)
3. My bad English. :(

Your English is actually pretty good.

Post by Gris Ge
I also intend to use markdown file to manually code down all C API and
Python API in human friendly way.

I updated the auto generated html from the doxygen:
http://libstoragemgmt.sourceforge.net/srcdoc/html/index.html

Thanks,
Tony

[Gris Ge]

Post by Tony Asleson

Post by Gris Ge
https://github.com/cathay4t/libstoragemgmt-doc
2. It could integrate to upstream git repo with 'gh-pages' branch.
# We need discuss on "two repo vs one repo"
# Some document like 'known issues' might not link to code
# change(like SMI-S provider bugs). So I prefer to using
# separate git like 'libstoragemgmt-doc'.

Can you elaborate on this some more. I guess I'm not fully
understanding why you prefer 2 git repos to 1 with the documentation in
a branch and I'm not following the 'known issues' point.

In page:
http://cathay4t.github.io/libstoragemgmt-doc/doc/known_issues.html
we will record down known issue user might face.

Some know issue like 'No VPD83 for HDS AMS 2000 or older storage'
might be solved by vendor(I doubt HDS will do so) without any LSM code
update, keep them under track in code might odd as that's not our problem.

That's my only concern about storing documents in one git tree.

But the benefit on using single git tree for code and doc is we could
enforce any library changes come with detailed document change also.

Let me create one more demo for keeping doc in existing git repo.
It will be located at:
http://cathay4t.github.io/libstoragemgmt

Post by Tony Asleson

Post by Gris Ge
1. Cannot auto generate TOC(Table of Content).
https://github.com/isaacs/github/issues/215
manually generated table of contents
http://cathay4t.github.io/libstoragemgmt-doc/doc/quick_user_guide

I believe if you use asciidoc markdown you can get a TOC, but then you
lose other functionality.

I would like to stick with github favored markdown as they literally
use it everywhere(wiki, comments, pull request) in github.
I don't want to mess up with two syntax.

Post by Tony Asleson
I stubbed out some wiki pages and I was actually thinking that instead
of using a TOC, if each topic was placed on it's own page a person could
use the sidebar instead of a TOC for navigation.
see: https://github.com/libstorage/libstoragemgmt/wiki

For API document, you cannot break it into 20+ pages. We still need to
TOC or TOC-like sidebar.

I manual(and some short perl script) created some TOC, please check
these examples:
http://cathay4t.github.io/libstoragemgmt-doc/doc/py_api_user_guide.html
http://cathay4t.github.io/libstoragemgmt-doc/doc/install.html
http://cathay4t.github.io/libstoragemgmt-doc/doc/user_guide.html

Post by Tony Asleson

Post by Gris Ge
3. My bad English. :(

Your English is actually pretty good.

Thanks.

Post by Tony Asleson

Post by Gris Ge
I also intend to use markdown file to manually code down all C API and
Python API in human friendly way.

http://libstoragemgmt.sourceforge.net/srcdoc/html/index.html

Thanks.

Post by Tony Asleson
Thanks,
Tony

[Gris Ge]

Post by Gris Ge
Let me create one more demo for keeping doc in existing git repo.
http://cathay4t.github.io/libstoragemgmt

Done.
I also did some small tweaks.
https://github.com/cathay4t/libstoragemgmt/tree/gh-pages

I also found some concerns about keeping git pages files in existing
git tree:

1. How we handle document update pull request?
# Initially, there will be a lot document update, do we really
# need to FPM("fork -> pull request -> merge") workflow?
# Or maybe, let me do it in my repo(git commit --amend).
# Once everyone satisfied, we push it to upstream.
# After that, we do FPM workflow on future changes.

2. How we maintain 'master' branch and 'gh-pages'[1] branch.
# Keep every thing in 'master' branch and sync it with
# 'gh-pages' branch?

[1] 'gh-pages' branch is mandatory for github pages.

Post by Gris Ge

Post by Tony Asleson
I stubbed out some wiki pages and I was actually thinking that instead
of using a TOC, if each topic was placed on it's own page a person could
use the sidebar instead of a TOC for navigation.
see: https://github.com/libstorage/libstoragemgmt/wiki

For API document, you cannot break it into 20+ pages. We still need to
TOC or TOC-like sidebar.
I manual(and some short perl script) created some TOC, please check
http://cathay4t.github.io/libstoragemgmt-doc/doc/py_api_user_guide.html
http://cathay4t.github.io/libstoragemgmt-doc/doc/install.html
http://cathay4t.github.io/libstoragemgmt-doc/doc/user_guide.html

Please try these pages instead :
http://cathay4t.github.io/libstoragemgmt/doc/markdown/py_api_user_guide.html
http://cathay4t.github.io/libstoragemgmt/doc/markdown/install.html
http://cathay4t.github.io/libstoragemgmt/doc/markdown/user_guide.html

Post by Gris Ge
------------------------------------------------------------------------------
Dive into the World of Parallel Programming The Go Parallel Website, sponsored
by Intel and developed in partnership with Slashdot Media, is your hub for all
things parallel software development, from weekly thought leadership blogs to
news, videos, case studies, tutorials and more. Take a look and join the
conversation now. http://goparallel.sourceforge.net/
_______________________________________________
Libstoragemgmt-devel mailing list
https://lists.sourceforge.net/lists/listinfo/libstoragemgmt-devel