On Tue, Mar 24, 2015 at 06:00:38PM -0500, Tony Asleson wrote: > > 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'. > > 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
> > 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
>
> 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.
>
> 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
> > 3. My bad English. :(
>
> Your English is actually pretty good.
>
Thanks.
> > 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.
> Thanks,
> Tony
--
Gris Ge
signature.asc
Description: Digital signature
------------------------------------------------------------------------------ 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 Libstoragemgmt-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/libstoragemgmt-devel
