Maintaining project documentation

Question

Documentation

We have a project for which there is a certain amount of documentation - both for users and for programmers. Now it is stored in the wiki, which is not very convenient. Here's what I want:

1. Documentation should be kept in text files so that it can be driven under version control.
2. Preferably wiki formatting.
3. Each file is a section. You can put links in the text to sections and subsections.
4. You can insert images.
5. All this should be able to be generated in PDF or DOC with a clickable table of contents, with formatting, links, images preserved in the text.
6. The possibility of online viewing of the text on the site is desirable (as in ordinary wiki sites).

The options I see are:

1. Regular wiki engine. Can do everything except generate a single PDF with support for the above features. Although there are plugins that add this functionality (at least for mediawiki), I don't like the result of their work. For example, the book authoring tool at wikipedia.org generates a non-clickable table of contents that is not recognized as a table of contents and links that are not visible as links. Another problem with the wiki is that you can only work with the Internet. And I could edit local text files whenever I want.

2.TeX. I have no doubt that all of the above is feasible (except for wiki markup). But I do not think that this is the right and easy way. Nicely formatting a document in LaTeX is a problem for me.

3. Take a console wiki parser and finish it to fit your needs. For example, mwlib, which theoretically can export to PDF. But I haven't looked at what kind of PDF it generates yet.

What do you advise?

Answer 1

Sphinx
Markup in reStructuredText, each file can be either a section or a page, automatic generation of tables of contents with arbitrary depth, search through all documents with JavaScript, templating, API for extensions, generation in HTML, Windows HTML Help, LaTeX (for PDF) , man pages, plain text.
Example - http://docs.python.org

Answer 2

sharepoint is not suitable?
Sharepoint:
A set of web-based collaboration applications
Functionality for creating portals
Module for searching information in documents and information systems
Functionality for managing workflows and an enterprise-wide content management system
Module for creating forms for information entry
Functionality for business analysis

Answer 3

You can look at dokuwiki . This is a wiki engine, it works not with a database, but with text files.
Perhaps there are plugins for pdf as well. Everything else is there.

Answer 4

Found another solution on google.
PM.portal is a project portal based on the Microsoft SharePoint platform.

Answer 5

Look at doxygen, there is no wiki formatting and I'm not sure there is a clickable table of contents in the pdf, but everything else is definitely there.

Answer 6

And we used DITA - very convenient, everything was under version control, and how docbook generates whatever you want - the main thing is to write xslt (there are several ready-made out of the box)

Answer 7

We are using asciidoc . Your points 1-5 can be done out of the box, browsing through the website is done through a trivial script (you can take my asciidoc.cgi ). Here is the article "Using asciidoc to document a project" .