ford

ford copied to clipboard

Hi Chris,

I have not yet used Ford, thus I may be wrong, but reading your doc it seems that the output is only html. I suppose that inside Ford you first build markdown files, is it right? It would be very useful to have also the possibility to have markdown output besides the html one.

See you soon.

That not exactly how it works. Any doc-comments are processed by markdown and held in a string by whatever object they are documenting. The documentation is actually produced using Jinja2 templates. It would certainly be possible to provide Markdown (or possibly even LaTeX) output, but it would require me to write a whole new set of Jinja2 templates. This is not a trivial task, especially as a lot of the logic of the program is actually contained within the templates. I may do it at some point, but I won't be at the moment.

However, this is something which someone else could certainly work on. Basically, what it would require is you to copy all of the files in ford/templates into a new directory and convert them to Markdown. You'd probably want to decide on whether you needed all of the files, too. You'd then just have to change ford/output.py slightly so that, if specified, it will load templates from this new directory, instead of the old one.

Hi Chris,

Thanks for the explanation. Presently, I have no time, but never say never. Maybe I will try to contribute on this.

See you soon.

Hi Chris,

I have a question not strictly related to this topic, but I can contact you only in this way...

I have just realized that the "engine" of Ford does a similar work of what I have tried to implent into the engine of MaTiSSe. However, I have done a bad work, rewriting many things that other guys have already made better than me. In particular, you have done a great work using jnija2 and beautifulsoup. I would like to use them. Can you give a link to some good starting point for learning and using them? MaTiSSe parses markdown and builds html, this should similar to Ford that parses fortran to obtain html...

Thank you very much!

For Jinja2 I just used their documentation. http://jinja.pocoo.org/docs/dev/templates/ explains how to build templates, while http://jinja.pocoo.org/docs/dev/api/ explains how to call Jinja2 from your program. My use of BeautifulSoup is minimal, to be honest, and I essentially just copied what others had done in similar circumstances. So I can't really recommend were to learn about it.

Ok, thank you.

I'm going to close this issue due to inactivity. If someone wants to implement this, or discuss particulars of their proposed design we can re-open or create a new issue.

Thanks!

I'm raising the dead here, but with the ability of GitHub Pages to automatically render project markdown files into a hosted website, it seems that leveraging the markdown-processed doc comments to produce markdown output is a worthy endeavor. At least, this feature would reduce the friction to actually hosting the documentation, especially for projects already on GitHub.

Rendering to markdown might also make it easier to use e.g. Jekyll themes too (see also #280). I'm reopening this, it seems like a useful thing to do if someone has time!

@chucklesoclock You might also be interested in this Github Action I wrote that auto-builds FORD docs on pushes to the main branch and commits them to the gh-pages branch: https://github.com/stellaGK/stella/blob/master/.github/workflows/docs.yml It's sort of a static Github Pages: hosted on Github, but doesn't need to run Jekyll etc

@ZedThree I am definitely interested! However, the projects I wish to build FORD documentation on live outside of Github and would require some form of access control. But hmm, it looks like Github has easy settings for that. Perhaps this can be a push towards joining the rest of the world here. Will definitely check your action out though, many thanks!