Merge pull request #128 from willingc/docs-devel

Add the basic structure for a Developer's Guide.

This is great! Thank you!

docs/conf.py

@@ -51,7 +51,7 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'BBC Microbit Micropython'
+project = u'BBC micro:bit MicroPython'
 copyright = u'2015, Multiple authors'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -106,7 +106,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+# html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -135,7 +135,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -204,7 +204,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  ('index', 'BBCMicrobitMicropython.tex', u'BBC Microbit Micropython Documentation',
+  ('index', 'BBCMicrobitMicropython.tex', u'BBC micro:bit MicroPython Documentation',
    u'Multiple authors', 'manual'),
 ]
 
@@ -248,7 +248,7 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'BBCMicrobitMicropython', u'BBC Microbit Micropython Documentation',
+  ('index', 'BBCMicrobitMicropython', u'BBC micro:bit MicroPython Documentation',
    u'Multiple authors', 'BBCMicrobitMicropython', 'One line description of project.',
    'Miscellaneous'),
 ]
@@ -338,3 +338,13 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
+
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# otherwise, readthedocs.org uses their theme by default, so no need to specify it

docs/devguide/devfaq.rst

@@ -0,0 +1,15 @@
+.. _devfaq:
+
+=============
+Developer FAQ
+=============
+
+.. note::
+
+    This project is under active development. Please help other
+    developers by adding tips, how-tos, and Q&A to this document.
+    Thanks!
+
+Where do I get a copy of the DAL? A: Ask Nicholas Toll for details.
+
+

docs/devguide/flashfirmware.rst

@@ -0,0 +1,55 @@
+.. _flashfirmware:
+
+=================
+Flashing Firmware
+=================
+
+Building firmware
+-----------------
+Use yotta to build.
+
+Use target bbc-microbit-classic-gcc-nosd::
+
+  yt target bbc-microbit-classic-gcc-nosd
+
+Run yotta update to fetch remote assets::
+
+  yt up
+
+Start the build::
+
+  yt build
+
+
+The result will be a microbit-micropython hex file (i.e. ``firmware.hex``)
+found in the build/bbc-microbit-classic-gcc-nosd/source from the root of the
+repository.  You will use the hex file to flash onto the micro:bit device
+
+There is a also a Makefile provided that does some extra preprocessing of the source,
+which is needed only if you add new interned strings to ``qstrdefsport.h``. The
+Makefile also puts the resulting firmware at build/firmware.hex, and includes
+some convenience targets.
+
+Preparing firmware and a Python program
+---------------------------------------
+
+tools/makecombined
+
+hexlify
+
+
+
+Flashing to the micro:bit
+-------------------------
+
+
+
+
+**Installation Scenarios**
+
+* :ref:`Windows <microbit-windows>`
+* :ref:`OS X <microbit-osx>`
+* :ref:`Linux <microbit-linux>`
+* :ref:`Debian and Ubuntu <microbit-debian-ubuntu>`
+* :ref:`Red Hat Fedora/CentOS <microbit-redhat>`
+* :ref:`Raspberry Pi <microbit-rpi>`

docs/devguide/installation.rst

@@ -0,0 +1,90 @@
+.. _install-dev:
+
+============
+Installation
+============
+
+This section will help you set up the tools and programs needed for
+developing programs and firmware to flash to the BBC micro:bit using MicroPython.
+
+Dependencies
+------------
+
+
+Development Environment
+-----------------------
+
+You will need::
+
+* git
+* yotta
+*
+
+Depending on your operating system, the installation instructions vary. Use
+the installation scenario that best suits your system.
+
+Installation Scenarios
+----------------------
+
+* :ref:`Windows <microbit-windows>`
+* :ref:`OS X <microbit-osx>`
+* :ref:`Linux <microbit-linux>`
+* :ref:`Debian and Ubuntu <microbit-debian-ubuntu>`
+* :ref:`Red Hat Fedora/CentOS <microbit-redhat>`
+* :ref:`Raspberry Pi <microbit-rpi>`
+
+
+.. _microbit-windows:
+
+Windows
+~~~~~~~
+
+
+.. _microbit-osx:
+
+OS X
+~~~~
+
+
+.. _microbit-linux:
+
+Linux
+~~~~~
+
+These steps will cover the basic flavors of Linux and working with the
+micro:bit and MicroPython. See also the specific sections for Raspberry Pi,
+Debian/Ubuntu, and Red Hat Fedora/Centos.
+
+
+.. _microbit-debian-ubuntu:
+
+Debian and Ubuntu
+^^^^^^^^^^^^^^^^^
+
+sudo add-apt-repository -y ppa:terry.guo/gcc-arm-embedded
+sudo add-apt-repository -y ppa:pmiller-opensource/ppa
+sudo apt-get update
+sudo apt-get install cmake ninja-build gcc-arm-none-eabi srecord
+pip3 install yotta
+
+
+.. _microbit-redhat:
+
+Red Hat Fedora/CentOS
+^^^^^^^^^^^^^^^^^^^^^
+
+
+.. _microbit-rpi:
+
+Raspberry Pi
+^^^^^^^^^^^^
+
+
+
+.. _next-steps:
+
+Next steps
+----------
+
+Congratulations. You have installed your development environment and are ready to
+begin :ref:`flashing firmware <flashfirmware>`  to the micro:bit.

docs/devguide/repl.rst

@@ -0,0 +1,40 @@
+.. _dev-repl:
+
+==================
+Accessing the REPL
+==================
+
+Accessing the REPL on the micro:bit requires:
+
+    * Using a serial communication program
+    * Determining the communication port identifier for the micro:bit
+    * Establishing communication with the correct settings for your computer
+
+Serial communication
+--------------------
+
+To access the REPL, you need to select a program to use for serial communication.
+Some common options are `picocom` and `screen`. You will need to install
+program and understand the basics of connecting to a device.
+
+Determining port
+----------------
+
+The micro:bit will have a port identifier (tty, usb) that can be used by the computer for
+communicating. Before connecting to the micro:bit, we must determine the port identifier.
+
+Establishing communication with the micro:bit
+---------------------------------------------
+
+Depending on your operating system, environment, and serial communication program,
+the settings and commands will vary a bit. Here are some common settings for different
+systems (please suggest additions that might help others)
+
+**Settings**
+
+* :ref:`Windows <microbit-windows>`
+* :ref:`OS X <microbit-osx>`
+* :ref:`Linux <microbit-linux>`
+* :ref:`Debian and Ubuntu <microbit-debian-ubuntu>`
+* :ref:`Red Hat Fedora/CentOS <microbit-redhat>`
+* :ref:`Raspberry Pi <microbit-rpi>`

docs/index.rst

@@ -3,13 +3,24 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to BBC Microbit MicroPython's documentation!
-====================================================
+BBC micro:bit MicroPython documentation
+=======================================
 
-Contents:
+Welcome to the project! We hope you enjoy developing for the BBC micro:bit
+using MicroPython.
+
+To get involved with the community subscribe to the microbit@python.org
+mailing list (https://mail.python.org/mailman/listinfo/microbit).
+
+.. note::
+
+    This project is under active development. Please help other
+    developers by adding tips, how-tos, and Q&A to this document.
+    Thanks!
 
 .. toctree::
    :maxdepth: 2
+   :caption: API Reference
 
    api_design_heuristics.rst
    microbit_micropython_api.rst
@@ -24,11 +35,19 @@ Contents:
    i2c.rst
    uart.rst
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Developer Guide
 
-Indices and tables
-==================
+   devguide/installation
+   devguide/flashfirmware
+   devguide/repl
+   devguide/devfaq
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-