Comments (6)
It was originally designed so commands like txt2man, man2html, and pandoc could take the output from the fpm CLI and automatically generate man-pages, markdown, and HTML documentation. It could be done in a CD/CI script on github so that each version had it's own set of documents and/or be included in the distributions or as tar balls on the fpm-docs page as well.
Considering you have to follow certain simple rules for the flat text to convert to man-pages via txt2man it is somewhat surprising that there seems to be little or no changes required, as that was never formally adopted but it was designed to be automated and part of the PR process originally, at least in my imagination :> The fact it is not already automated seems to indicate some resistance to the idea but I have never seen it verbalized; but in a CD/CI script with fpm installed you just wget txt2man and you can do things like "fpm --help|txt2man >man/man1/fpm.1fpm" for each of the topics to generate the manpages; and then use one of the other tools to convert the man-pages to markdown, HTML, and so on. I use such at automated process for essentially all my own repositories so the documents are automatically extracted from the code and turned into man-pages and html, and a CLI interface that can be used as an fpm plugin that I like to use for libraries. Not sure everyone should go there but the part using prep(1) and making the input text files is the oddest part and not needed for fpm which already has help text, so it seems reasonable to me. Maybe instead of changing all various fpm install packages some separate man-page package that contained fpm and stdlib man-pages would be useful for Unix-like-systems; and the above methods could be used to post md/HTML to the fpm-docs pages.
from fpm-docs.
I showed a couple of examples of doing this, as the original design of the help text was intended to be automatically converted to man-pages and HTML. I misplaced the best script, but it should be pretty easy to put it into a CI/CD script (I did it once as a demo, must be on another box but I am sure I kept it) that converted it to HTML. I tried going to markdown and I think the best result is in manual_2.md in the docs directory in https://github.com/urbanjost/fpm-tools/tree/main/docs so far. Assuming we can clean it up how does that look? The HTML that gets generated from the man-pages is not that great technically but I think looks better, but when I used pandoc to convert the HTML back to markdown it came out worse than just going straight to markdown from the manpages using pandoc, I think. The txt2man and man2html files are on the same site explicitly so they can be easily accessed from a build script, as they are modified from the originals. I had to tweek txt2man to do a better job with Fortran.
from fpm-docs.
Once question is to whether to make a single document or to make a page for each topic and make an index. The index might be a little harder to automate, but it looks like pandoc might be able to do that automatically. Have not tried it. I think trying to automate it is worth it, as it is still changing frequently.
from fpm-docs.
Looking at cargo it looks like it also releases the help as man-pages. That is definitely easy as that is exactly what it is designed for, so just run through the modified txt2man(1), if that is desirable.
from fpm-docs.
@urbanjost @awvwgk I would like to document some changes i.e. fpm returning an application's exit code. I've done that in the FORD documentation (fortran-lang/fpm#858) but as @henilp105 @arteevraina suggested that's not straightforward to find. I was thinking to document the fpm CLI in a new Markdown page on fpm-docs but then I've stumbled upon this thread.
Where should I do that?
Looking at Cargo, it seems like they also manually maintain .md
pages, which are then deployed to both a website and man pages.
So, would that be enough for now if I add .md
pages to the current Sphynx site? As we have more Markdown pages, that could grow with time, to become a full documentation site like Cargo has.
Another option is to add to the current FORD documentation but I don't like it as much, it's harder to navigate and not as visually appealing.
from fpm-docs.
Thank you @urbanjost for the explanation. So, the original idea was to extract documentation from the Fortran code into the man pages and possibly the documentation site. This is basically the opposite that Cargo seems to be doing, where the documentation site is built manually (not from the source code) even if the man pages are still built automatically from that.
I would personally lean towards using the same approach (Markdown pages -> man pages), because I think Markdown is free form and easier to collaborate upon here on GitHub, but maybe it would be nice to have other opinions on what's the best direction before taking any endeavor? @certik @awvwgk
from fpm-docs.
Related Issues (20)
- Install Instructions for Homebrew Mac Broken
- migrate to setup-micromamba from provision-with-micromamba HOT 1
- Restructuring of the fpm docs HOT 5
- bug: website deploys before merging to main HOT 3
- maint: enable dependabot alerts
- French translation / Traduction en Français HOT 8
- Dutch translation / Nederlandse vertaling HOT 20
- Use fpm logo HOT 1
- Update fpm plugin tutorial
- Japanese translation HOT 2
- Dependency management
- Host fpm registry HOT 1
- Remove `❯` from code-blocks to make copy-pasted code runnable HOT 2
- Rebuild with cron job
- Add Bengali (bn) translation
- Add Polish (pl) translation
- MacPorts has fpm port HOT 3
- Source file scoping specification
- Source file scoping specification
- Hindi translation HOT 2
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 fpm-docs.