Sunday, 16 April 2017

cldoc - a promising documentation generator

cldoc needs Python 2, and won't yet work with Python 3. You have to make sure it's at least Python 2.7.9 so that you get pip.exe, which will be needed to install various extras. After installing Python 2, run:

python -m ensurepip --upgrade

to get pip, then:

pip install pyparsing

You might have to do this from C:\Python27\Scripts. If you don't want to replace your Python 3 setup in Path and PYTHONPATH, just calling "pip install", even from the Python 2 directory, will run the pip for Python 3.

You may need the latest Clang: older versions don't all have full support for C++14 features on Windows.

Create a Sublime Text build system, called cldoc.sublime-build, and fill it with:
 "cmd": ["C:\\Python27\\python.exe","C:\\PATH TO\\cldoc-dev","generate","--","--output","C:/PATH TO/docout","C:/PATH TO/*.h"]
 ,"env": {"PYTHONPATH":"C:\\Python27"}
,"file_regex": "^(.*)\\:([0-9]*)\\:([0-9]*)\\:"

Testing the docs in Windows

To test the documentation website on Windows, you must install Jekyll. Follow the instructions. Watch out for the SSL errors. Once you have jekyll on your Windows machine, you can go to the site directory and call e.g.:
jekyll build --incremental --destination G:/

That destination part is because the links to css files etc start with a slash. So the only way you can test this locally is if the site is at the root of some directory.
Create a small partition on your local drive, and put the site there.

.htaccess for XAMPP:

Options +FollowSymLinks -MultiViews
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_URI} !-f
RewriteRule ^([a-zA-Z0-9_-]+)$ $1.html