Documentation

[ci5er]

Good day,

1) Have you considered making your documentation files a part of your repository? They would both serve as examples as well as be something that others could edit and contribute back. I know that if I ever take systems to a new platform, I usually will contribute a build+install guide. Often I will include a shoot trouble-shooting section where I got stuck, or add additional material in those areas.

2) It appears that the documentation files were themselves originally done as .md files. If so, your smartfences section .md file would be a great example. I say this selfishly as I still haven't gotten the sequence diagrams and flow charts to work on either of the systems I have installed this on yet.

Thanks!

[facelessuser]

1) Have you considered making your documentation files a part of your repository? They would both serve as examples as well as be something that others could edit and contribute back. I know that if I ever take systems to a new platform, I usually will contribute a build+install guide. Often I will include a shoot trouble-shooting section where I got stuck, or add additional material in those areas.

They are part of the repository, they are just on a github pages branch: https://github.com/facelessuser/PyMdown/tree/gh-pages. And they are generated with this app. I am still sort of figuring out how how I ultimately want things to work in the end. It is sort of an experiment and a work in progress. To be honest I originally just wrote this to make bulk generation of markdown easier for me and add in a number of custom plugins I wrote (https://github.com/facelessuser/pymdown-extensions), I never really thought too much about usage of the app outside of myself (but I have no problem with anyone coming in and using it or even offering suggestions or pulls). I keep a server for myself at work where I store all sorts of useful info for myself in markdown and generate a static site were I can access the info. I always kind of figured I'd make the plugins available on a separate repo that people could use; and I kind of figured that is what most people would be interested in, but if people want to use the main app as well, they are welcome to. I do plan on eventually adding the plugins repo to the Python Markdown wiki as I think they are now pretty stable.

2) It appears that the documentation files were themselves originally done as .md files. If so, your smartfences section .md file would be a great example. I say this selfishly as I still haven't gotten the sequence diagrams and flow charts to work on either of the systems I have installed this on yet.

Yes, they totally are and as mentioned above can be viewed at the github pages branch. The important thing is letting PyMdown know where it is getting the Javascript for sequence diagrams and flowcharts etc as they do the bulk of the work. The superfences (that is its new name) extension just makes exceptions for special flow and sequence blocks and preserves the content and marks them with a special class name for the javascript files to target. If you are having trouble, I would be more than happy to help you through it. I think for the sequence diagrams, I just use an online CDN to include the Javascript, flowcharts I directly include the script as there is currently no CDN. I also have a couple of small javascript files that search for the appropriate elements and apply the appropriate js library to the element:

https://github.com/facelessuser/PyMdown/blob/gh-pages/js/uml-converter.js (This is a general method that hunts for the given class name and applies the given converter and settings.

https://github.com/facelessuser/PyMdown/blob/gh-pages/js/sequence-loader.js (tells the above convert method to look for the sequence diagram elements and use the diagram library.)

https://github.com/facelessuser/PyMdown/blob/gh-pages/js/flow-loader.js (tells the above convert method to look for flowchart elements and use the flowchart library.)

All of this files and are available at the github pages repo and if you dig through the repo, you can see exactly how I utilize everything https://github.com/facelessuser/PyMdown/tree/gh-pages. If you get confused on how I am doing something, feel free to ask. SuperFences documentation markdown is found here: https://github.com/facelessuser/PyMdown/blob/gh-pages/Extensions/SuperFences.md.

I hope this helps.

[ci5er]

Thank you.

I should have seen the gh-pages thing, but my mother apparently didn't have any smart children.

I'm trying to pull together a thing for engineers that makes documentation just-about-as simple as sending an e-mail. I've got a thing that works, but it is very server-intensive with the PlantUML and what not. I think that StackEdit started making me think that there might be a lighter way to do it.

I knew how to (using your fragments/components) pull together by hand the elements that would make a sequence diagram (for example) work -- it just wasn't compiling up that way. It's probably a templating thing. I may come back if I can't figure it out.

For what it's worth -- I like your SuperFences parser better than the Python Markdown fenced code parser. Maybe I'm just not a parsing guy...

Thank you and best regards,

W. Archibald

On Sat, Jan 10, 2015 at 9:00 PM, Isaac Muse notifications@github.com wrote:

1) Have you considered making your documentation files a part of your repository? They would both serve as examples as well as be something that others could edit and contribute back. I know that if I ever take systems to a new platform, I usually will contribute a build+install guide. Often I will include a shoot trouble-shooting section where I got stuck, or add additional material in those areas.

They are part of the repository, they are just on a github pages branch: https://github.com/facelessuser/PyMdown/tree/gh-pages. And they are generated with this app. I am still sort of figuring out how how I ultimately want things to work in the end. It is sort of an experiment and a work in progress. To be honest I originally just wrote this to make bulk generation of markdown easier for me and add in a number of custom plugins I wrote (https://github.com/facelessuser/pymdown-extensions), I never really thought too much about usage of the app outside of myself (but I have no problem with anyone coming in and using it or even offering suggestions or pulls). I keep a server for myself at work where I store all sorts of useful info for myself in markdown and generate a static site were I can access the info. I always kind of figured I'd ma ke the p lugins available on a separate repo that people could use; and I kind of figured that is what most people would be interested in, but if people want to use the main app as well, they are welcome to. I do plan on eventually adding the plugins repo to the Python Markdown wiki as I think they are now pretty stable.

2) It appears that the documentation files were themselves originally done as .md files. If so, your smartfences section .md file would be a great example. I say this selfishly as I still haven't gotten the sequence diagrams and flow charts to work on either of the systems I have installed this on yet.

Yes, they totally are and as mentioned above can be viewed at the github pages branch. The important thing is letting PyMdown know where it is getting the Javascript for sequence diagrams and flowcharts etc as they do the bulk of the work. The superfences (that is its new name) extension just makes extensions for special flow and sequence blocks and preserves the content and marks them with a special class name for the javascript files to target. If you are having trouble, I would be more than happy to help you through it. I think for the sequence diagrams, I just use an online CDN to include the Javascript, flowcharts I directly include the script as there is currently no CDN. I also have a couple of small javascript files that search for the appropriate elements and apply the appropriate js library to the element:

https://github.com/facelessuser/PyMdown/blob/gh-pages/js/uml-converter.js (This is a general method that hunts for the given class name and applies the given converter and settings.

https://github.com/facelessuser/PyMdown/blob/gh-pages/js/sequence-loader.js (tells the above convert method to look for the sequence diagram elements and use the diagram library.)

https://github.com/facelessuser/PyMdown/blob/gh-pages/js/flow-loader.js (tells the above convert method to look for flowchart elements and use the flowchart library.)

All of this files and are available at the github pages repo and if you dig through the repo, you can see exactly how I utilize everything https://github.com/facelessuser/PyMdown/tree/gh-pages. If you get confused on how I am doing something, feel free to ask. SuperFences documentation markdown is found here: https://github.com/facelessuser/PyMdown/blob/gh-pages/Extensions/SuperFences.md .

I hope this helps.

Reply to this email directly or view it on GitHub https://github.com/facelessuser/PyMdown/issues/33#issuecomment-69481620.

[facelessuser]

No problem. Engineers at my work just don't document anything, or it is outdated and spread out everywhere. I mainly did this to host my own documentation after I piece info together, and then I point people there who want to know the same info.

I'm glad you like superfences. It took me a couple of iterations to get it right, but I am fairly pleased with the end results.

[ci5er]

It's been a long time since I was in the trenches, but at Motorola we were expected to document everything about our chips before they were built -- and then test to make sure the silicon matched our published specs.

At a long-ago start-up, one thing that was more-or-less handy and used was simply a per-team e-mail list. Anyone could subscribe to be in any group to 'watch' -- all team members were part of it. There was a spool dumped, and that was html-ized (pipermail) and indexed. When people joined six-months later, they could search for similar issues.

Wikis were 'ok', but people didn't update them. Our captured institutional knowledge was in those e-mail threads. Since we were dashing off e-mails anyway, all I would ask of the guys is that they use 1~3 tags in the subject and a more-or-less complete English subject line summarizing the question being asked. Or the statement being made.

IF I can get this stream-lined enough to where people are having environment, setup, protocol and code discussions by e-mail ... with VERY little additional work and nothing outside of their already existent "workflow", we might even be able to capture documentation fodder.

I can dream.

And, yeah -- I don't know how long that Superfence parsing code took to write, but it was certainly easier than the python Markdown fenced code segment to read. I have to tell you the truth though ... I would rather sling 100,000 lines of C code at a rendering project than have to write high-level-language magic code for a living.

Best Regards,

W. Archibald

On Sat, Jan 10, 2015 at 9:40 PM, Isaac Muse notifications@github.com wrote:

No problem. Engineers at my work just don't document anything, or it is outdated and spread out everywhere. I mainly did this to host my own documentation after I piece info together, and then I point people there who want to know the same info.

I'm glad you like superfences. It took me a couple of iterations to get it right, but I am fairly pleased with the end results.

Reply to this email directly or view it on GitHub https://github.com/facelessuser/PyMdown/issues/33#issuecomment-69482402.