Hi there,
I'm working on a project[0] to build a documentation website using buildbot. We have plenty of publican books for me to play with, but I'd also like to enable other formats. ReStructuredText[1] seems like a good first choice, as it's easy to learn and use (just squint and pretend it's markdown, if you aren't familiar), and there are processors for it at hand.
Anerist is centered around consuming git repositories. Ultimately, I'd like the site to offer the both user and contributor facing documentation. I also need a repo full of RST content to bang out implementation details. infra-docs.git seems ideally positioned to help out here, and any time invested would carry forward to the end product. Each article would need some kind of header[2] to work at scale, though.
So, what does the infrastructure team think about writing in RST? If I'm willing to convert everything over, are you willing to sustain it?
--Pete
[0] slowly, anyway... https://github.com/immanetize/anerist [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html [1b] more digestable: http://www.getnikola.com/quickstart.html [2] Probably something like https://lists.fedoraproject.org/pipermail/docs/2015-March/016101.html, discussion encouraged.
I've personally never written RST, but if its similar to markdown, maintaining docs should be pretty simple.
On Tue, Apr 14, 2015, 8:00 PM Pete Travis lists@petetravis.com wrote:
Hi there,
I'm working on a project[0] to build a documentation website using buildbot. We have plenty of publican books for me to play with, but I'd also like to enable other formats. ReStructuredText[1] seems like a good first choice, as it's easy to learn and use (just squint and pretend it's markdown, if you aren't familiar), and there are processors for it at hand.
Anerist is centered around consuming git repositories. Ultimately, I'd like the site to offer the both user and contributor facing documentation. I also need a repo full of RST content to bang out implementation details. infra-docs.git seems ideally positioned to help out here, and any time invested would carry forward to the end product. Each article would need some kind of header[2] to work at scale, though.
So, what does the infrastructure team think about writing in RST? If I'm willing to convert everything over, are you willing to sustain it?
--Pete
[0] slowly, anyway... https://github.com/immanetize/anerist [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html [1b] more digestable: http://www.getnikola.com/quickstart.html [2] Probably something like https://lists.fedoraproject.org/pipermail/docs/2015-March/016101.html, discussion encouraged.
infrastructure mailing list infrastructure@lists.fedoraproject.org https://admin.fedoraproject.org/mailman/listinfo/infrastructure
On Tue, 14 Apr 2015 18:00:42 -0600 Pete Travis lists@petetravis.com wrote:
Hi there,
I'm working on a project[0] to build a documentation website using buildbot. We have plenty of publican books for me to play with, but I'd also like to enable other formats. ReStructuredText[1] seems like a good first choice, as it's easy to learn and use (just squint and pretend it's markdown, if you aren't familiar), and there are processors for it at hand.
Anerist is centered around consuming git repositories. Ultimately, I'd like the site to offer the both user and contributor facing documentation. I also need a repo full of RST content to bang out implementation details. infra-docs.git seems ideally positioned to help out here, and any time invested would carry forward to the end product. Each article would need some kind of header[2] to work at scale, though.
So, what does the infrastructure team think about writing in RST? If I'm willing to convert everything over, are you willing to sustain it?
I think when we started infra-docs we just wanted simple...
I have no objection to standardizing them to use a common markup and header. I'm not sure how much good they would do other people published out to the world, as they are very specific in many cases to our infrastructure, but perhaps someone would find them of use.
I could see a use if there was a way to say publish them as epub. Then infra folks might be able to have them locally in smartphones or tablets in case online wasn't practical for some outage or other reason.
kevin
On Apr 15, 2015 10:11 AM, "Kevin Fenzi" kevin@scrye.com wrote:
On Tue, 14 Apr 2015 18:00:42 -0600 Pete Travis lists@petetravis.com wrote:
Hi there,
I'm working on a project[0] to build a documentation website using buildbot. We have plenty of publican books for me to play with, but I'd also like to enable other formats. ReStructuredText[1] seems like a good first choice, as it's easy to learn and use (just squint and pretend it's markdown, if you aren't familiar), and there are processors for it at hand.
Anerist is centered around consuming git repositories. Ultimately, I'd like the site to offer the both user and contributor facing documentation. I also need a repo full of RST content to bang out implementation details. infra-docs.git seems ideally positioned to help out here, and any time invested would carry forward to the end product. Each article would need some kind of header[2] to work at scale, though.
So, what does the infrastructure team think about writing in RST? If I'm willing to convert everything over, are you willing to sustain it?
I think when we started infra-docs we just wanted simple...
I have no objection to standardizing them to use a common markup and header. I'm not sure how much good they would do other people published out to the world, as they are very specific in many cases to our infrastructure, but perhaps someone would find them of use.
I could see a use if there was a way to say publish them as epub. Then infra folks might be able to have them locally in smartphones or tablets in case online wasn't practical for some outage or other reason.
kevin
epub should be feasible, given standardized markup. I could even supply those to some known location fairly soon after conversion, it doesn't have to wait for anerist's front-end generator bits to be worked out.
--Pete
--Pete
infrastructure@lists.fedoraproject.org