Maybe not "frequently asked", but hopefully these answers will be useful.
If you want lots of control over the resulting documentation: no.
If you want to hook in API docs and such: no.
If you want to write in something other than Markdown: no.
If you have a large project and need more than one level of organization for your documentation: no.
If you have a small project and want to quickly write some docs that don't look like ass: yes!
If your documentation starts to need some more structure or functionality, you can easily switch over to Sphinx in a few minutes:
There's nothing tricky about this process because d has almost no
process/configuration of its own. All you do when using d is create pure
content. This makes switching to other tools simple a matter of converting this
content to their preferred format.
Your webserver should add a trailing slash to directories. Most sane ones do that by default these days, so you should be all set.
If you're using a server that doesn't, you might need to add a rewrite rule so
URLs like /foo redirect to /foo/.
d's goal is to be quick, easy, and get out of your way. Most web servers will
serve the folder structure d creates sanely without any extra configuration.
This also lets you type links such as [installation guide](/installation/),
instead of requiring you to add the .html.
Sure. You'll need to use relative links in your content pages though:
See the [installation guide][ig] for more information. [ig]: ../installation/
The <base> tag is a clusterfuck. Just add the dots. Trust me.
Sure, make the filenames start with numbers and a dash, like this:
01-installation.markdown 02-usage.markdown
d will order the files properly, but ignore the number when creating the
URLs, so you still get nice links like /installation/.
No, use a different tool.
Sure. Remember that Markdown lets you add raw HTML anywhere. Just put the HTML
in footer.markdown and you're all set.
Not yet, but it's on my radar.
Put [TOC] wherever you want it to appear. It will parse the headings in the
document, remove the first level (the page title) and output a nice list for
you.
Yep, just put :::lang at the beginning of your code blocks, like this:
:::python
for i in range(10):
print i
Not yet, but it's on my radar.
You need a real web server to preview the generated files effectively. Luckily, you already have one: Python comes with a built-in server that's great for viewing local files.
Build your docs, then in a separate terminal:
cd myproject/docs cd build python -m SimpleHTTPServer
Now open http://localhost:8000 and view your docs!
Yes, use peat to watch for changes and run d.
No, use a different tool.
No, auto-generated docs are a cop out. Sit down and write some real, hand-crafted documentation for humans.
No, use a different tool.
No, use a different tool.