[Owasp-leaders] Sharing experience of yet another way to publish documentation projects

Taras Ivaschenko taras.ivaschenko at owasp.org
Sun Feb 17 19:47:35 UTC 2019


Hello,

I see that last time some OWASP documentation projects migrated to
GitHub and text based formats plus various technologies to publish it.

In this letter I want just share yet another way to do it :) May be it
could be helpful for someone (like
https://www.owasp.org/index.php/OWASP_AppSec_Pipeline).

For Russian translation of OWASP Proactive Controls we used:
* GitHub for repository
(https://github.com/owasp-russia/top-10-proactive-controls)
* Sphinx (http://www.sphinx-doc.org) as documentation generator which
gives us various output format and l10n support out of box
* reStructuredText (https://en.wikipedia.org/wiki/ReStructuredText) as
base text format. It is similar to Markdown but much more powerful
* Popular documentation service called "Read The Docs"
(https://readthedocs.org/) as publishing platform and CI/CD service. So
we get free web hosting for result docs, multilanguage support,
auto-generated PDF, EPUB and HTML versions and other cool features. It
also has support for custom domain, so if we want we could have e.g.
https://docs.owasp.org/projects/foobar
* For localization we used special service Transifex
(https://www.transifex.com/). So translators don't need to fork original
English version and get easy to use special l10n service.

HTML version is available at
https://owasp-top-10-proactive-controls-2018.readthedocs.io/en/latest/

Feel free to ask questions.

-- 
Taras Ivashchenko
https://www.owasp.org/index.php/Russia

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://lists.owasp.org/pipermail/owasp-leaders/attachments/20190217/8d760d88/attachment.pgp>


More information about the OWASP-Leaders mailing list