-

[djfurman]

@eppye,

I'd love to help get the wiki stood up and operational for documentation, would you prefer a pull request to use the GitHub version or something like a readthedocs setup?

If you're interested in the assistance, please let me know which you would prefer and I'll get started on migrating the exported Wiki into full useable state in the format of your choice.

Thanks & looking forward to working with you.

-Dan

[skilchen]

@djfurman , @eppye

Hello,

I have already done some experiments in this direction: A working github wiki version of the documentation at http://github.com/skilchen/bots/wiki A working github-pages version of the documentation using MkDocs and their readthedocs theme at http://skilchen.github.io/bots_doc_b

please take a look at my experiments and reuse whatever might be useful ...

regards, Samuel

[eppye]

did some work on this, but think your results are much better than
mine .....

kind regards,

Henk-Jan Ebbers www.ebbersconsult.com t: 0031 30 2888358

Bots Open Source EDI Translator: http://bots.sourceforge.net Connect edi-partners at lower costs by smarter testing: www.edi-testrobot.com

On 02/17/2016 10:35 PM, skilchen wrote:

  @djfurman , @eppye 
  Hello,
  I have already done some experiments in this direction:
    A working github wiki version of the documentation at http://github.com/skilchen/bots/wiki
    A working github-pages version of the documentation using MkDocs
    and their readthedocs theme at http://skilchen.github.io/bots_doc_b
  please take a look at my experiments and reuse whatever might
    be useful ...
  regards,
    Samuel
  —
    Reply to this email directly or view
      it on GitHub.

[BikeMikeAU]

I really like the MkDocs version... nice layout (would be better if the navigation bar sections collapsed in levels), theme looks nice, search works well.

I agree we need to make a decision on "final" location of the official documentation, There have been several occasions recently I would have made updates... but where? Then all the wiki links within Bots GUI need to be updated; there are not many.

[BikeMikeAU]

The basic Github wiki allows easy editing as you browse, but how do you edit the MkDocs version?

[BikeMikeAU]

"Home" should go to introduction, not sidenavigation

[skilchen]

Thanks for the interest in my experiments.

The github repo for the MkDocs version is at http://github.com/skilchen/bots_doc_b I added you as a collaborator with push access. The collaboration probably would have to follow the normal github workflow:

• install MkDocs with pip install mkdocs
• clone the repository http://github.com/skilchen/bots_doc_b
• make/push your changes using git
• use mkdocs gh-deploy to build the MkDocs version and deploy it to the gh-pages branch of the repo
• view the changes at http://skilchen.github.io/bots_doc_b

you might try to modify my experimental version in this way ...

if @eppye likes it, he would then have to take the files in my repo back and create his own documentation repository.

unfortunately my MkDocs knowhow is minimal, so i don't know if it supports collapsible navigation bar sections.

[klaasfeenstra]

Hi,

I also think that this read the docs manual is very nice. For me it's not a very big problem that the sidebars is not collapsed.

Kind regards,

Klaas

On Thu, Feb 18, 2016 at 2:04 PM, skilchen notifications@github.com wrote:

Thanks for the interest in my experiments.

The github repo for the MkDocs version is at http://github.com/skilchen/bots_doc_b https://github.com/skilchen/bots_doc_b I added you as a collaborator with push access. The collaboration probably would have to follow the normal github workflow:

• install MkDocs http://www.mkdocs.org with pip install mkdocs
• clone the repository http://github.com/skilchen/bots_doc_b https://github.com/skilchen/bots_doc_b
• make/push your changes using git
• use mkdocs gh-deploy to build the MkDocs version and deploy it to the gh-pages branch of the repo
• view the changes at http://skilchen.github.io/bots_doc_b

you might try to modify my experimental version in this way ...

if @eppye https://github.com/eppye likes it, he would then have to take the files in my repo back and create his own documentation repository.

unfortunately my MkDocs knowhow is minimal, so i don't know if it supports collapsible navigation bar sections.

— Reply to this email directly or view it on GitHub https://github.com/eppye-bots/bots/issues/369#issuecomment-185710470.

[BikeMikeAU]

I think one big advantage of a wiki is the instant editing right there on the page. I don't know much about git workflow but sounds like it would just get in the way a bit. That would sway my preference back to the standard wiki.

[skilchen]

In the meantime i have merged the sphinx-docs branch from http://github.com/abhishek-ram/bots and made the html output produced by sphinx viewable at http://skilchen.github.io/bots

there is an open pull request for this version of the documentation at http://github.com/eppye-bots/bots. @abhishek-ram tried to enhance the structure of the docs. please check if you like his version of the documentation.

i agree with @BikeMikeAU regarding the advantage of the wiki version. the main advantages of the other two solutions sphinx and mkdocs are imho:

1. the searchability of the docs.
2. the possibility to host the produced html output everywhere where static html files can be hosted.
3. the readability on mobile devices is better.

[abhishek-ram]

@skilchen and @BikeMikeAU we can still make the changes to documentation on the github UI.

What we need to do is go to the appropriate .rst file in your clone and make the needed changes. Once change has been made open a PR so that it is updated in the master clone. Once the PR is approved and merged the read-the-docs site is automatically updated with the changes.

[eppye]

that version http://skilchen.github.io/bots
is very good.

but how does it work?
can you explain something about it?
(I did experiment with ReadTheDocs. ReadTheDocs makes documentation
based on github repository. But this is on GitHub itself?)

How can I fetch this?
 (I am sorry, I am not very familiar with this?)

kind regards,
henk-jan ebbers

On 02/22/2016 03:54 AM, skilchen wrote:

  In the meantime i have merged the sphinx-docs branch from http://github.com/abhishek-ram/bots
    and made the html output produced by sphinx viewable at http://skilchen.github.io/bots
  there is an open pull request for this version of the
    documentation at http://github.com/eppye-bots/bots.
    @abhishek-ram tried to enhance the
    structure of the docs. please check if you like his version of
    the documentation.
  i agree with @BikeMikeAU
    regarding the advantage of the wiki version. the main advantages
    of the other two solutions sphinx and mkdocs are
    imho:

    the searchability of the docs.
    the possibility to host the produced html output everywhere
      where static html files can be hosted. 
    the readability on mobile devices is better.

  —
    Reply to this email directly or view
      it on GitHub.

[skilchen]

@eppye-bots the version you like is the one produced by @abhishek-ram You already have a pull request for this version in your repo. I think the easiest way for you to proceed is then:

1. merge the pull request into your main repository
2. change your readthedocs project to import http://github.com/eppye-bots/
3. setup the webhook as described in the readthedocs documentation

Now whenever you push something to your main repository the documentation at readthedocs will automatically be rebuilt.

If you prefer to host your documentation as gh-pages on github, then the "easiest" procedure would be somewhat like:

1. merge the pull request into your main repository
   • or in your local clone pull my current experiment (it should merge automatically)
2. change into the new docs subdirectory
3. assuming you already have sphinx installed, execute: make dirhtml
4. change dir into _build/dirhtml
5. execute: git init
6. execute: git checkout --orphan gh-pages
7. create a .nojekyll file, on unix like systems with: touch .nojekyll
8. execute: git add .
9. execute: git commit -m "some commit message"
10. execute: git push <url of your github repo> gh-pages

and finally go to http://<your github username>.github.io/<github repo name> and check if you see your documentation.

next time you make some changes to your documentation, you only have to execute the following steps:

1. change dir into docs
2. make dirhtml
3. change dir into _build/dirhtml
4. git add .
5. git commit -m "some other commit message"
6. git push <url of your github repo> gh-pages

evidently hosting the documentation on readthedocs.org is much simpler... my fork of your work including the contribution by @abhishek-ram is now also hosted on readthedocs

the mkdocs people have made these steps invisible with their highly useful command: mkdocs gh-deploy. unfortunately something similar is not yet available in sphinx.

btw. in my repo i changed @abhishek-ram's index.rst to start with the table of content. using this structure the readthedocs site produces a reasonably good pdf version of your documentation.

[eppye]

thank you, will check that out this weekend!

kind regards,
henk-jan

On 03/03/2016 09:17 PM, skilchen wrote:

  @eppye-bots the version you like is
    the one produced by @abhishek-ram

    You already have a pull request for this version in your repo.
    I think the easiest way for you to proceed is then:

    merge the pull
        request into your main repository
    change your readthedocs project
      to import http://github.com/eppye-bots/

    setup the webhook as described in the readthedocs
        documentation

  Now whenever you push something to your main repository the
    documentation at readthedocs will
    automatically be rebuilt.
  If you prefer to host your documentation as gh-pages on github,
    then the "easiest" procedure would be somewhat like:

    merge the pull
        request into your main repository

        or in your local clone pull my current
            experiment (it should merge automatically)

    change into the new docs subdirectory
    assuming you already have sphinx installed, execute: make
        dirhtml

    change dir into _build/dirhtml

    execute: git init

    execute: git checkout --orphan gh-pages

    create a .nojekyll file, on unix like systems with: touch
        .nojekyll

    execute: git add .

    execute: git commit -m "some commit message"

    execute: git push <url of your github repo>
        gh-pages

  and finally go to http://<your github
      username>.github.io/<github repo name> and
    check if you see your documentation.
  next time you make some changes to your documentation, you only
    have to execute the following steps:

    change dir into docs

    make dirhtml
    change dir into _build/dirhtml

    git add .
    git commit -m "some other commit message"
    git push <url of your github repo> gh-pages

  evidently hosting the documentation on readthedocs.org is much
    simpler... my fork of your work including the contribution by @abhishek-ram is now also hosted on readthedocs
  the mkdocs
      people have made these steps invisible with their highly
    useful command: mkdocs gh-deploy. unfortunately
    something similar is not yet available in sphinx.
  btw. in my repo i changed
    @abhishek-ram's index.rst to start
    with the table of content. using this structure the readthedocs
    site produces a reasonably good pdf version of your
    documentation.
  —
    Reply to this email directly or view
      it on GitHub.

[eppye]

probably I did something wrong.
that gits-hub what ever thing is not quite clear.

can that 'pull request' be doen agian? Is the possible?

kind regards,

Henk-Jan Ebbers www.ebbersconsult.com t: 0031 30 2888358

Bots Open Source EDI Translator: http://bots.sourceforge.net Connect edi-partners at lower costs by smarter testing: www.edi-testrobot.com

On 03/03/2016 09:17 PM, skilchen wrote:

  @eppye-bots the version you like is
    the one produced by @abhishek-ram

    You already have a pull request for this version in your repo.
    I think the easiest way for you to proceed is then:

    merge the pull
        request into your main repository
    change your readthedocs project
      to import http://github.com/eppye-bots/

    setup the webhook as described in the readthedocs
        documentation

  Now whenever you push something to your main repository the
    documentation at readthedocs will
    automatically be rebuilt.
  If you prefer to host your documentation as gh-pages on github,
    then the "easiest" procedure would be somewhat like:

    merge the pull
        request into your main repository

        or in your local clone pull my current
            experiment (it should merge automatically)

    change into the new docs subdirectory
    assuming you already have sphinx installed, execute: make
        dirhtml

    change dir into _build/dirhtml

    execute: git init

    execute: git checkout --orphan gh-pages

    create a .nojekyll file, on unix like systems with: touch
        .nojekyll

    execute: git add .

    execute: git commit -m "some commit message"

    execute: git push <url of your github repo>
        gh-pages

  and finally go to http://<your github
      username>.github.io/<github repo name> and
    check if you see your documentation.
  next time you make some changes to your documentation, you only
    have to execute the following steps:

    change dir into docs

    make dirhtml
    change dir into _build/dirhtml

    git add .
    git commit -m "some other commit message"
    git push <url of your github repo> gh-pages

  evidently hosting the documentation on readthedocs.org is much
    simpler... my fork of your work including the contribution by @abhishek-ram is now also hosted on readthedocs
  the mkdocs
      people have made these steps invisible with their highly
    useful command: mkdocs gh-deploy. unfortunately
    something similar is not yet available in sphinx.
  btw. in my repo i changed
    @abhishek-ram's index.rst to start
    with the table of content. using this structure the readthedocs
    site produces a reasonably good pdf version of your
    documentation.
  —
    Reply to this email directly or view
      it on GitHub.

[skilchen]

you can either revert your revert or rewrite the history using git reset --hard 3ba4b56 to undo the mistake after you merged the pull request

then you probably have to use --force to push the changes back to github: git push --force origin master

[woutervh]

@skilchen: I 've sent you an invite to the github "bot-edi" organisation. I hope you can merge all your documentation efforts in the official bots-repository, once it's transferred.