Sphinx prototype Documentation Release 0.1 Arthur Mar 03, 2017
General documentation 1 Support docs 3 2 Developer docs 5 3 API docs 7 3.1 About this setup............................................. 7 3.2 Setting up your development environment................................ 9 3.3 Setting up your testing environment................................... 9 3.4 Installing the application......................................... 10 3.5 Running the app............................................. 12 i
ii
Refer to the About this setup General documentation 1
2 General documentation
CHAPTER 1 Support docs link 1 link 2 3
4 Chapter 1. Support docs
CHAPTER 2 Developer docs Setting up your development environment Installing the application 5
6 Chapter 2. Developer docs
CHAPTER 3 API docs API overview What s new About this setup This setup uses rest as markup language and is built using the Sphinx website generator. Standard CMS vs static website generators Static website generators have noticable advantages for documentation: Pro: Free. Generally open-source. No vendor lock-in. Website is built in a few minutes. Pages load extremely fast. Extremely easy to customize. No DB to take care of and protect from hacking. Edit content in any offline editor. No need for Internet or proprietary software. i18n is generally a standard feature. Fast to install and deploy when setting up a documentation framework. Cons: It can be more difficult to manage the docs if the folder structure changes. 7
Editing complicated content can be a bit more tedious than with dedicated software. Lightweight markup languages and website generators There are 3 big families: 1. Markdown and any static website generator, like Jekyll. 2. AsciiDoc and any static website generator, like Jekyll. 3. rest and Sphinx. The choice of the generator impacts the features of the website and the ease of maintenance of the docs, so the generator has to been chosen carefully. Sphinx is the go-to generator for rest. They were built to be used together but other generators can read rest files through helpers. rest vs Markdown vs AsciiDoc I have not tested AsciiDoc yet but why is rest better than Markdown? Standard and future-proofing 1. Markdown has no standard but flavours that have implemented standards. Each flavour renders a bit differently. They can potentially be difficult to convert to another markup language. 2. rest has a standard. If there is a need to switch to MD or anything else in the future, Pandoc can convert rest to anything that has a standard. 3. Sphinx and rest were designed for documentation. 4. Sphinx/reST are built in Python, and we have Python developpers if we ever need advanced extensions. On the other hand, Markdown is widely used and will evolve more quickly than rest. Features for documentation Features required: Feature Markdown + Jekyll & co rest + Sphinx Easy linking Yes Yes Fast publishing Yes Yes Easy output customization Yes Yes Conditional content Depends on the generator Yes Reusable content Depends on the generator Yes Additional plugins Yes Yes Search Depends on the generator Yes In-content TOC Depends on the generator Yes Doc specific styles and taxo Depends on the Markdown flavour Yes TOC features (hide entries, Depends on the generator Yes numbered sections...) Possiblity to add HTML classes/att Yes: write HTML inside the MD files (mixing languages) Yes: with rest directives (cleaner) 8 Chapter 3. API docs
Learning curve rest is not as simple as Markdown but a day is enough to get the basics. Setting up your development environment To start developing Android-based Fire TV apps for the Amazon Fire TV platform, you need to first set up your development environment. Set Up the JD You need the Java Development Kit (JDK) from Oracle to compile Java apps on your machine. First check to see if you already have the JDK. Open Terminal or Command Prompt and type java -version. If you have the JDK, the response should be something like this: java version "1.8.0_101" Java(TM) SE Runtime Environment (build 1.8.0_101-b13) Java HotSpot(TM) 64-Bit Server VM (build 25.101-b13, mixed mode) If you don t have the JDK, download the version of the JDK Installer for your machine from Java SE Development Kit Downloads and run it. For more details, see the following: 10 JDK 8 Installation for OS X 10 JDK 8 Installation for Windows For other operating systems and information, see JDK 8 and JRE 8 Installation Start Here. Set Up Android Studio Install Android Studio, the official IDE for Android projects. Next Steps To connect your development computer to your Fire TV device with ADB, see Connecting to Fire TV Through ADB Setting up your testing environment Installing Multiple Python Versions The Simple Way The simplest way to install multiple Python versions is from the the Deadsnakes PPA. From the command line run the following commands:.. code-block:: bash $ sudo add-apt-repository ppa:fkrull/deadsnakes $ sudo apt-get update $ sudo apt-get install python3.1 python3.2 python3.3 3.2. Setting up your development environment 9
Adjust that last line to only list the supported versions of Python which are not already installed on the system. Now, typing pythonx.x on the command line will run Python version X.X:.. code-block:: bash $ python3.1 version Python 3.1.5 $ python3.2 version Python 3.2.6 Yes, it is that easy. Skip down to the [Installing the Testing Tools][tt] section to continue. The Hard Way If you don t want to or can t install from a PPA, then the simplest approach is to install from source into /opt. Apparently, /opt is where one would install optional packages. Additionally, by installing from source with the changed location, each Python version would be completely contained within a directory within /opt. If one ever wants to remove a version, all one needs to do is delete that directory and any associated links. The first step is to ensure that all dependencies are installed for the currently installed Python version. Run the following once: $ python version Python 2.7.2+ $ sudo apt-get build-dep python2.7 Installing the Testing Tools Once all of the Python versions are installed, the tools used to run the tests need to be installed. However, they will only need to be installed for the system s default Python version as virtual environments will be created by tox to run the tests in. If they re not already installed, download and install [virtualenv] s dependencies:: $ wget http://python-distribute.org/distribute_setup.py $ sudo python distribute_setup.py $ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py $ sudo python get-pip.py Run the Tests Now that everything is set up, the tests can be run. First a copy of the source needs to be cloned from [Github]: $ git clone git@github.com:<username>/python-markdown.git md Be sure to replace <username> above with our own Github username. You are cloning from your own fork right? How else will you create pull requests to get your changes committed upstream? If the development virtual environment created earlier isn t active, activate it and run the tests in the default Python version: $ cd md $ workon md (md)$./run-tests.py (md)$ deactivate Installing the application This page describes a generic install procedure with several sections. Preparing your environment Install the app the regular way 10 Chapter 3. API docs
Make a development workspace Checking the installation Installing the test module Running the test Note: This is a note that is being reused from another file. Preparing your environment Install the app the regular way Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nibh dolor, ullamcorper nec nulla sed, bibendum imperdiet libero. Fusce lectus tellus, elementum ut facilisis nec, ultricies ac magna. Suspendisse venenatis, tortor in lobortis facilisis, nisi augue dictum diam, in faucibus justo lectus eget massa. Nullam id ultrices metus. 1. do this. 2. click button. Important: That s important 3. delete the :path. The file is deleted. 4. run make that. (a) sub item 1 1 (b) sub item 2 5. paste this ruby code where needed 2 #!/usr/bin/env ruby puts 'Hello world' puts 'It works' Warning: don t mess it up. Make a development workspace Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nibh dolor, ullamcorper nec nulla sed, bibendum imperdiet libero. Fusce lectus tellus, elementum ut facilisis nec, ultricies ac magna. Suspendisse venenatis, tortor in lobortis facilisis, nisi augue dictum diam, in faucibus justo lectus eget massa. Nullam id ultrices metus. Etiam mattis magna eros, et condimentum enim molestie a. 1 First footnote 2 Second footnote 3.4. Installing the application 11
See also: How to do that using ::command::build. Checking the installation Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nibh dolor, ullamcorper nec nulla sed, bibendum imperdiet libero. Fusce lectus tellus, elementum ut facilisis nec, ultricies ac magna. Suspendisse venenatis, tortor in lobortis facilisis, nisi augue dictum diam, in faucibus justo lectus eget massa. Nullam id ultrices metus. Etiam mattis magna eros, et condimentum enim molestie a. Installing the test module Whatever blablaballbalbalbalba Running the test Blablablablablablabla that s it. Running the app This page describes how to run the application. Note: This is a note that is being reused from another file. First execution 1. do this. 2. do that. 3. click button. 4. run make that. 5. do this. 6. do that. Blablablabla Following executions 1. do this. 2. click button. Important: That s important 12 Chapter 3. API docs