# HG changeset patch # User Steve Losh # Date 1327365499 18000 # Node ID 6d25e2bfb2fe20cea8d2dca8294d26b8f33a21d1 # Parent c9e5e7f76b20b74fb89c9c12b7a6a70d5be4bd9e d: Update site. diff -r c9e5e7f76b20 -r 6d25e2bfb2fe d/01-installation.markdown --- a/d/01-installation.markdown Mon Jan 23 19:34:25 2012 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,14 +0,0 @@ -Installation -============ - -You just need Python and `pip`: - - :::bash - pip install d - -You can use `easy_install` if you really want: - - :::bash - easy_install d - -`d` uses Markdown, Pygments, and Pyquery to do some of the heavy lifting. diff -r c9e5e7f76b20 -r 6d25e2bfb2fe d/02-usage.markdown --- a/d/02-usage.markdown Mon Jan 23 19:34:25 2012 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,135 +0,0 @@ -Usage -===== - -`d` is designed to be easy and intuitive to use. Here's a whirlwind tour that -will get you up and running in five minutes. - -[TOC] - -Basic Flow ----------- - -Make a directory for your docs: - - :::bash - mkdir docs - cd docs - -Write some docs: - - :::bash - touch index.markdown - touch installation.markdown - touch usage.markdown - - vim . - -Render your docs: - - :::bash - d - -Copy the output somewhere: - - :::bash - rsync -d build/ myserver:/var/www/myproject - -The Introduction Page ---------------------- - -The text of the main page (above the table of contents) comes from the -`index.markdown` file. - -This page doesn't need a title. Just write out the text you want to show above -the table of contents. - -The Footer ----------- - -The contents of the footer comes from `footer.markdown`. - -Documentation Files -------------------- - -There are a few rules to follow when writing docs for use with `d`. They should -be pretty intuitive once you try them out. - -### Extensions - -You can use `.markdown`, `.mdown`, or `.md` as the extension for your Markdown -files. `d` doesn't care. - -### Layout - -Each Markdown file (other than the introduction and footer) is rendered as -a separate page. - -### Page Titles - -Every page other than the introduction needs a level 1 heading as the first -line. It will be used as the title of the page. - -### Other Headings - -There shouldn't be any other level 1 headings. Levels 2/3/4/5/6 are fine. - -### Links - -Link to other documents by using their filenames with no extension. - -For example: the URL for `usage.markdown` would be `/usage/`. - -### Relative URLs - -If you're planning on serving these docs at a URL other than `/` you should add -`..` before links to other pages. - -For example: the URL for `usage.markdown` would now be `../usage/`. - -**Note:** these relative URLs are safe to use even when you're serving the docs -at `/`, so there's no disadvantage to using them other than a bit more typing. - -### Tables of Contents - -Use `[TOC]` to display a table of contents for the current page, if you want -one. - -Example -------- - -Here's a sample documentation file to get you started: - - :::markdown - Installation - ============ - - Here's how to install my project. - - If you just want to see how to use it, take a look at the [samples][] page. - - [samples]: /samples/ - - [TOC] - - Linux - ----- - - Use your package manager. - - Windows - ------- - - It depends on what version of Windows you have. - - ### Windows XP - - ... - - ### Windows Vista - - ... - - ### Windows 7 - - ... - diff -r c9e5e7f76b20 -r 6d25e2bfb2fe d/03-customization.markdown --- a/d/03-customization.markdown Mon Jan 23 19:34:25 2012 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,36 +0,0 @@ -Customization -============= - -`d` is mostly designed for quick and dirty use. There are a few customization -options, but if you find yourself wanting more you probably need a different -tool. - -[TOC] - -Project Title -------------- - -`d` tries to intelligently guess your project's title. You can override it by -creating a `title` file with the title inside. - -Page Titles ------------ - -`d` takes page titles from the first line of the file, which should be a level -1 Markdown heading. - -Page URLs ---------- - -The URL for each page will be the filename of the page, without an extension. -For example, `usage.markdown` will have a URL of `/usage/`. - -There is one exception: if a filename starts with a number and a dash, `d` will -ignore those for the URLs (but will sort on them, so you can use this to reorder -pages). - -Footer ------- - -The contents of the footer are rendered from `footer.markdown`, or left blank if -you don't have it. diff -r c9e5e7f76b20 -r 6d25e2bfb2fe d/04-faqs.markdown --- a/d/04-faqs.markdown Mon Jan 23 19:34:25 2012 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,129 +0,0 @@ -FAQs -==== - -Maybe not "frequently asked", but hopefully these answers will be useful. - -[TOC] - -Should I use d for my project? ------------------------------- - -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!** - -Web Servers and File Layout ---------------------------- - -### Do I need to do anything special with my webserver? - -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/`. - -### Why does d use page/index.html instead of page.html? - -`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`. - -### Can I serve the documentation at a URL other than /? - -Sure. You'll need to use relative links in your content pages though: - - :::markdown - See the [installation guide][ig] for more information. - - [ig]: ../installation/ - - -### Why can't I use to have normal-looking links? - -The `` tag is a clusterfuck. Just add the dots. Trust me. - -### Can I reorder the pages? - -Sure, make the filenames start with numbers and a dash, like this: - - :::text - 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/`. - -### Can I create multiple folders/sections? - -No, use a different tool. - -Page Content ------------- - -### Can I add a Google Analytics script? - -Sure. Remember that Markdown lets you add raw HTML anywhere. Just put the HTML -in `footer.markdown` and you're all set. - -### Can I add media? - -Not yet, but it's on my radar. - -### Can I display a table of contents for a single page? - -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. - -### Can I have syntax highlighting for code snippets? - -Yep, just put `:::lang` at the beginning of your code blocks, like this: - - :::text - :::python - for i in range(10): - print i - -### Can I add HTML into the of the docs? - -Not yet, but it's on my radar. - - -Writing Tools -------------- - -### Can I make d auto-rerender when my files change? - -Yes, use [kicker](https://github.com/alloy/kicker) to watch for changes and run -`d`. - -### Kicker is only for OS X, what about Linux? - -I haven't found a tool like kicker for Linux, sorry. - -Let me know if you write one -- I've wanted it for a while now. - -### Can I write in something other than Markdown? - -No, use a different tool. - -### Can I add auto-generated documentation into d's docs? - -No, auto-generated docs are a cop out. Sit down and write some real, -hand-crafted documentation for humans. - -### Can I output to PDF/ePub/man pages/etc? - -No, use a different tool. - diff -r c9e5e7f76b20 -r 6d25e2bfb2fe d/base --- a/d/base Mon Jan 23 19:34:25 2012 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1 +0,0 @@ -/build/ diff -r c9e5e7f76b20 -r 6d25e2bfb2fe d/footer.markdown --- a/d/footer.markdown Mon Jan 23 19:34:25 2012 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,15 +0,0 @@ -Created by [Steve Losh](http://stevelosh.com). Inspired by [t](http://stevelosh.com/projects/t/). - - diff -r c9e5e7f76b20 -r 6d25e2bfb2fe d/index.markdown --- a/d/index.markdown Mon Jan 23 19:34:25 2012 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,18 +0,0 @@ -Comic - -You need to write documentation. `d` makes it easy: - -* Put a bunch of Markdown files in a directory. -* Run `d`. -* Get on with your life. - -No fiddling around with configuration files, themes, version numbers, -obtuse markup, or multiple output formats. - -Make some Markdown files. Run `d`. Move on. - -`d` is open source on [BitBucket][] and [GitHub][]. It's MIT/X11 licensed. - -[BitBucket]: http://bitbucket.org/sjl/d -[GitHub]: http://github.com/sjl/d diff -r c9e5e7f76b20 -r 6d25e2bfb2fe d/publish.sh --- a/d/publish.sh Mon Jan 23 19:34:25 2012 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,7 +0,0 @@ -#!/usr/bin/env bash - -~/lib/virtualenvs/d/bin/python ../bin/d -hg -R ~/src/sjl.bitbucket.org pull -u -rsync --delete -az . ~/src/sjl.bitbucket.org/d -hg -R ~/src/sjl.bitbucket.org commit -Am 'd: Update site.' -hg -R ~/src/sjl.bitbucket.org push diff -r c9e5e7f76b20 -r 6d25e2bfb2fe d/title --- a/d/title Mon Jan 23 19:34:25 2012 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1 +0,0 @@ -d