Restructured Text and Sphinx

Restructured text is the broadly-supported approach to documenting Python code. It's basically a set of conventions to format text files through the use of punctuation, using the same basic approach that many people have used in contexts like email and readme files. Restructured Text basically formalized these hokey conventions into a slightly hokey set of rules that can be used to put together readable, formatted text files, which can be processed using utilities like Sphinx:

http://www.sphinx-doc.org/en/stable/

Sphinx is a documentation engine, developed to generate formatted documentation of source code. It is mainly designed to support Python projects, and it has cool features for documentation of Phython code. It can pull in structured comments (called Docstrings) directly from source code, using directives like automodule, autoclass and autofunction. Most importantly, it has the ability to assemble documents into a single internally-linked document structure, using things like toctree. Here's an example of an RST file for Sphinx:

.. Note This is a template for meeting notes.

  Update this as appropriate.

.. header:: Notes: Stephen

.. meta-data fields for Sphinx:

.. index:: template

.. sectionauthor:: Stephen 

.. Substitutions here:

.. |reST| replace:: reStructuredText

.. image:: ./image.png

.. sidebar:: callouts

    Include callouts here

Template: Notes

==============================================

Topic:

-------

#. Topic 1

#. Topic 2

#. Topic 3

This file is entitled "Template: Notes". It's got a lot of comments at the beginning, including the header and sectionauthor field. It contains a substitution directive, which lets you type "reST" instead of "reStructuredText". It inserts an image into the document and has a sidebar comment. When this is rendered in Sphinx, it will all get assembled into a document format of your choice: html, pdf or even ePub. 

Lately, I've discovered that RST/Sphinx is actually a pretty good answer to note taking applications like Microsoft OneNote and Evernote. RST files are lightweight and easy to read, and when assembled by Sphinx, they constitute a highly readable notebook that can be used to track personal notes over time (including searching and indexing.

I'd recommend taking a look at RST and Sphinx. The Sphinx engine is available for download from here: http://www.sphinx-doc.org/en/stable/. I've included a cheat-sheet of my favorite Sphinx terms below:

Marissa Mayer and the Fight to Save Yahoo! - Nicholas Carlson

Of the accounts of Silicon Valley business adventures that I have read this year, this is without a doubt the most fascinating. I have come away with a new impression of Marissa Mayer's efforts to save Yahoo!. I had regarded Marissa's tenure to be at some level, a refutation of the Google approach--one which seems to work well in a company that already has an unprecedented first mover advantage and is wondering what to do with all of the money that it keeps accumulating, but doesn't really work in a competitive market. My new appraisal is more complex: she actually did a lot for the company, but far from enough. 

More than any other company, Yahoo's history traces that of the Internet, from its early days as a "Jerry and David's Guide to the World Wide Web" in 1994, it has been a company focused on bringing the Internet to middle America. In its early days, 'The Internet' constituted a focused goal in and of itself, but as middle america came to embrace the Internet and our grandparents became adept at social media, nobody really needed a Yahoo to explain it to them. After a lot of fascinating history of early Internet companies including a failed takeover by Microsoft, Nicholas Carlson sets the stage for Marissa's messiah-like entrance in 2012 and leadership until its eventual acquisition by Verizon which wrapped up earlier this year. 

Marissa sought to bring Yahoo! forward into the modern Internet era. She made changes to the workplace that made Yahoo! more closely resemble a modern Silicon Valley company, including all those double-edged perks which make it so hard to stay away from work. I suppose that if Yahoo! had, in fact, come up with something totally revolutionary like an 'iPad' or a cloud computing platform, it might still be independent and we would all be singing Marissa's praises still. Steve Jobs breathed new life into Apple after his famous return in 1997, but this is because Steve's are amazing. Yahoo! did come out with impressive news, sports and entertainment services, acquired Tumblr and generally got better. However, no products were compelling enough to make Yahoo! the That! company, unless 'That!' is peanut butter, spread to thin or perhaps the world's largest data-breech company, including 500*10^6 user accounts in 2014. Without any deep insight, this appears to have been a legacy of Yahoo's continuous history from the insecure 90s, when security was not generally taken seriously, rather than any of Marissa's actions, but it does seem to have been the iceberg that struck the Titanic. 

Carlson provides an engrossing cautionary tale of a company that just couldn't decide what it wanted to be and ended up as nothing in the end. He does a great job of placing you in the room:

"It was Thursday: November 7, 2013. Everyone in the company was waiting for Mayer to say something to remind them that she was the CEO who was finally going to restore Yahoo to its rightful place in the Internet industry.

Mayer took a breath. She said hello to everyone. She reminded them of the meeting’s confidentiality. She said she looked through their questions and she had something she wanted to read. It had been a book in her hands, after all. A children’s book.
She began to read.

"Bobbie had a nickel all his very own. Should he buy some candy or an ice cream cone?"
Mayer held the book up, to show the employees the illustrations.
"Should he buy a bubble pipe? Or a boat of wood?"
Another illustration.
"Maybe, though, a little truck would be the best of all!"
Employees in URLs exchanged looks. At their desks, employees in remote offices grew confused.
What was Mayer doing?
She kept reading.
"Bobbie sat and wondered, Bobbie sat and thought. What would be the NICEST thing a nickel ever bought?"

Mayer seemed to skip a few pages. She read, with a slight agitation in her voice:
"He might buy a bean bag or a top to spin. He might buy a pin-wheel to give to little Brother. Or should he buy, thought Bobbie, a little pencil box?"

Mayer seemed to be reading with real frustration now, as though all of the anger and confusion in the room would just go away if everyone would just understand the story she was reading out loud.

“Bobbie thought—and suddenly a bright idea came,” Mayer read, reaching the book’s last pages.
"He spent his nickel just like this - - - -"
Mayer held the book up to show its last illustration. It was a drawing of a little red-haired boy riding a merry-go-round pony.
Hardly anyone could see the page.
No one understood what Mayer was trying to say.

Perhaps she should have read Marie Kondo's The Life-Changing Magic of Tidying Up: The Japanese Art of Decluttering and Organizing.

Book review: Brain on Fire

Brain on Fire - Susannah Cahalan

• This was an entertaining first-person account of the author's experience of a rare autoimmune disease, anti-NMDA receptor encephalitis. This is one of the most well-researched first person medical narrative that I've encountered. Ito stood out from other works in this limited genre in its extensive inclusion of personal details, obtained retrospectively by the author from her own medical record. She manages to provide a large amount of technical details about the disease without interrupting the emotional thread of this narrative. 
• This book brought back personal memories for me, as I found myself recalling a guest seminar on anti-NMDA receptor encephalitis from my days in graduate school. This provided me with a new perspective on this illness. 
• After Googling this title, it looks like it's being made into a movie.