Sphinx JS HowTo Documentation

Transcription

1 Sphinx JS HowTo Documentation Release Damon Oehlman August 09, 2012

2

3 CONTENTS i

4 ii

5 Sphinx JS HowTo Documentation, Release This is a how-to that guides developers through the process of creating documentation for their JS libraries, using Sphinx. While I originally favoured tools such as Markdown and the Github wiki, I found it difficult to keep things up to date. Using Sphinx and online services such as made things feel much more managable. The guide is designed to be use in conjuction with the Sphinx Documentation and references to that material are made when it makes sense. If this guide does not specifically mention how to do something, then be sure to search the Sphinx Documentation also. CONTENTS 1

6 Sphinx JS HowTo Documentation, Release CONTENTS

7 CHAPTER ONE GETTING STARTED Release Date August 09, Introduction Getting started with Sphinx and restructuredtext (in particular) can be a little daunting. This is especially true if you have come from the rather wonderfully simple world of markdown and friends. As daunting as it may be, let me assure you it is worth working through some short term pain for long term gain. 1.2 Linking Pages Creating meaningful links between pages in your documentation will make your users love you, and while it s a little confusing at first it makes a lot of sense in the long run. I would suggest that making your documentation nicely linkable works best if you can get yourself into a few particularly useful habits: Labelling Sections Give every section of your documentation a meaningful label. For instance, the top of this page looks like the following:.. _linking-pages: ============= Linking Pages ============= Once you have labelled a section, you then reference it with a reference link: :ref: linking-pages Which generates a link with the section title as the text, e.g. Linking Pages. Additionally, you can title the reference: :ref: Stuff about Linking Pages <linking-pages> Which becomes Stuff about Linking Pages. 3

8 Sphinx JS HowTo Documentation, Release Chapter 1. Getting Started

9 CHAPTER TWO DOCUMENTING YOUR CODE Firstly, you should have a look at the Showing Code Examples information in the Sphinx Documentation as it is already a very complete guide. 5

10 Sphinx JS HowTo Documentation, Release Chapter 2. Documenting Your Code

11 CHAPTER THREE WORK SMARTER, NOT HARDER Writing documentation isn t fun, but it is important. Important for it to exist and to be accurate. Personally, I find keeping documentation up to date to be very difficult. For this reason, it s important to work smarter, not harder when documenting your library. Here are a few tips: 3.1 Include Your Readme The first page of your documentation is likely to be pretty much the same as the README you have in your package repository. Why not save yourself the trouble of trying to keep that in sync by simply using a rst include directive. If your docs live in the docs folder then the following should do the job nicely:.. include::../readme.rst Of course, if you aren t yet using restructuredtext to format your README, then this won t work. Perhaps it s time to consider a change? 7

12 Sphinx JS HowTo Documentation, Release Chapter 3. Work Smarter, Not Harder

13 CHAPTER FOUR TOOLS 9

14 Sphinx JS HowTo Documentation, Release Chapter 4. Tools

15 CHAPTER FIVE QUICK TIPS This section of the howto includes short RST snippets covering how to do simple things. It is far from definitive, so make sure you consult the complete rst Reference for more information 5.1 Including Images Images are included using the image directive:.. image:: <image-path> 5.2 Use a Central links file I ve found it particularly useful to centralize all of my links in a central links.txt file, such as the one shown below:.. _Sphinx: _Sphinx Documentation: _showing code examples: _restructuredtext: _rst Reference: _directive: _markdown: Once you have this file, you can then include it with a simple include statement and have those links correctly interpreted on any page in your documentation: ========= Test Page ========= This test page is about markdown _... include:: links.txt 11