Comments (9)
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.
from ford.
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.
from ford.
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!
from ford.
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.
from ford.
Ok, thank you.
from ford.
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!
from ford.
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.
from ford.
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
from ford.
@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!
from ford.
Related Issues (20)
- FORD 7.0.1: AttributeError: 'FortranSubmodule' object has no attribute 'deplist' HOT 9
- Wrong parsing of @end* at end of file HOT 2
- `|page|`, `|media|`, and `|url|` are absolute instead of relative HOT 4
- Can not start a new line in Fortran with "&" HOT 4
- Ford 7.0.1: AttributeError: 'str' object has no attribute 'name' HOT 11
- fixed2free2 as a Python dependency? HOT 1
- Upgrade bundled javascript files HOT 1
- Use a maintained javascript search engine HOT 1
- External projects missing some information
- Refactor `_find_chain_item`
- Add more projects to corpus tests HOT 4
- Exception when resolving links in docstrings of deferred bound methods HOT 1
- Search field requires non-slim version of jQuery
- Issue on page /index.html
- Problems with graphs: crash and truncated HOT 4
- pcpp cannot handle our code: What's the best path forward? HOT 6
- --external_link option broken after redesign of external project handling HOT 1
- multiprocessing error when using graph_dir HOT 2
- Aliases in tables HOT 2
- HTML encoding non-breaking spaces in parameter initial values
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from ford.