search

cnjinhao / nana-refman

The content of nana reference manual
1 stars 1 forks source link

Previewing modifications #3

Open JamesBremner opened 5 years ago

JamesBremner commented 5 years ago

The formatting markup seems to be a little unusual, so I would like to be able to see a preview of any changes BEFORE committing the change. As it is, if I mess up the formatting, I have to make several commits just to get it fixed. Is there somewhere I can paste a text file so I can see what it is going to look like?

cnjinhao commented 5 years ago

There is a method mentioned in README.md. So the URL looks like(from the your forked repo)

http://nanapro.org/en-us/documentation/page.php?u=/utilities/drawing&repo=https://raw.githubusercontent.com/JamesBremner/nana-refman/master/en-us

BTW, the docs is not written in markdown format. It's an exclusive format I created for rendering.

qPCR4vir commented 5 years ago

Hi, I know this kind of problems. When I try to modify and debug the .travis for CI I have to go and commits and push, etc. to see the result. I propose you bookmark:

http://nanapro.org/en-us/documentation/page.php?u=/utilities/drawing&repo=https://raw.githubusercontent.com/JamesBremner/nana-refman/master/en-us

this will be your viewer. And bookmark:

https://github.com/JamesBremner/nana-refman/edit/master/en-us/content/utilities/drawing.txt

this is your editor. I tested it and works not too bad. Open each in a different window or tab of your browser. Make changes, view in preview changes, commit, all in the editor and then just refresh the viewer tab. I just created https://github.com/cnjinhao/nana-refman/pull/4 this way.

JamesBremner commented 5 years ago

@cnjinhao wrote:

BTW, the docs is not written in markdown format. It's an exclusive format I created for rendering.

This seems to me like a really bad idea. Now at a minimum you have to provide documentation for your documentation formatting, at best a WYSIWYG editor.

@qPCR4vir wrote:

I propose ....

Yes, that is the technique I used. It does not solve the problem. I have to do a commit before I can see what kind of a mess I made of things. So github ends up with a long trail of embarrassing typo fixes.

You need to think through again how you expect people to contribute to documentation. I would suggest:

A: A brief reference manual for each widget to orientate newbies, written in plain HTML with links to the doxygen docs on a server somewhere.

B: Insistence that code pull requests must have doxygen comments introducing every public method that was added or modified.

( You almost have this now, except the reference manual is too hard to maintain so becomes out of date and utterly confusing for newbies and the doxygen documentation at http://qpcr4vir.github.io/nana-doxy/html/index.html is not well linked to and is often disapointingly silent on many methods. )