DocTools.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notes, 12/29/17\n",
    "* Decided to use Sphinx/ReadTheDocs instead of GitHub Pages since Sphinx/ReadTheDocs is independent of GitHub\n",
    "* Tutorial\n",
    "    * http://dont-be-afraid-to-commit.readthedocs.io/en/latest/documentation.html#documentation-using-sphinx-and-readthedocs-org\n",
    "    * create anaconda environment for documentation\n",
    "        * conda create -n docs python=3.6 sphinx\n",
    "        * source activate docs\n",
    "    * create a git repository to hold the documentation (following directions on above website)\n",
    "        * mkdir ~/Documents/Sphinx/my-first-docs\n",
    "        * cd ~/Documents/Sphinx/my-first-docs\n",
    "        * git init\n",
    "        * git remote add origin git@github.com:srherbener/my-first-docs.git\n",
    "        * git checkout -b master\n",
    "        * mkdir docs\n",
    "        * sphinx-quickstart\n",
    "            * root directory --> docs\n",
    "            * separate source and build directories --> y\n",
    "            * name prefix for templates and static dirs --> hit return to leave as underscore\n",
    "            * project name --> Steve's first docs\n",
    "            * project id --> 1.0\n",
    "            * project release --> 1.0.1\n",
    "            * project language --> hit return to leave as english (en)\n",
    "            * source file suffix --> hit return to leave as .rst\n",
    "            * name of your master document --> hit return to leave as \"index\"\n",
    "            * want to use epub builder --> n\n",
    "            * say yes to all sphinx extensions except for imgmath and githubpages\n",
    "            * create makefile --> y\n",
    "            * create window command file --> n\n",
    "        * cd docs\n",
    "        * edit source/index.rst\n",
    "    * update github repository\n",
    "        * git commit -a\n",
    "        * git push origin master\n",
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notes, 1/22/18\n",
    "* Handy website for writing sphinx/rst:\n",
    "    http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html\n",
    "\n",
    "* Created ReadTheDocs website for JEDI\n",
    "    * Use this to experiment and to help make decision on whether to use Sphinx/ReadTheDocs\n",
    "    * Username: UcarJedi/YodaMaster3\n",
    "    * Associated this with my GitHub account for now\n",
    "        * Can't associate with UCAR GitHub account\n",
    "            * This is a company-wide account\n",
    "            * We don't have passwords (ie, all of us have to associate to our personal github accounts)\n",
    "* Tried connecting ReadTheDocs to UCAR/ufo\n",
    "    * Didn't work, permissions are not granted since this is a private repository\n",
    "    * Same problem when I tried forking UCAR/ufo to sherbener/ufo\n",
    "* ReadTheDocs will be good for:\n",
    "    * User guide\n",
    "    * Installation guide\n",
    "    * Static documents\n",
    "* Need something else for:\n",
    "    * Issue tracking\n",
    "    * Developer discussions\n",
    "    * Dynamic documents"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notes, 1/24/18\n",
    "* From yesterday's JEDI meeting, decided that we should look at a number of options for documentation tools\n",
    "    * This is show we can have a paper trail of why we chose what we did\n",
    "        * We eventually want to try and have all of JCSDA adopt the methodologies that we chose for JEDI\n",
    "* Will look at\n",
    "    * GitHub Pages\n",
    "    * Sphinx/ReadTheDocs\n",
    "    * Doxygen\n",
    "        * Can it do more than just API reference docs\n",
    "            * Man pages, guides, etc.\n",
    "    * R Studio\n",
    "        * Example of website\n",
    "        * Vignettes are nice\n",
    "            * User experiences\n",
    "* Need to check if document generators support LaTex\n",
    "    * Every person in yesterday's JEDI meeting said they want LaTex\n",
    "    * Very common in the science community\n",
    "* Created a public repository on GitHub called ufo_doc_test so that ReadTheDocs (free version) can access it.\n",
    "* ReadTheDocs has a 30-day trial of their professional version\n",
    "    * Called the Business version\n",
    "        * Basic\n",
    "            * \\$50/month = \\$600/year\n",
    "            * Public and private docs\n",
    "            * Uses ReadTheDocs domain to host documents\n",
    "        * Advanced\n",
    "            * \\$150/month = \\$1800/year\n",
    "            * Customize to fit company's brand\n",
    "            * Use company's domain to host documents\n",
    "    * Both business versions limit the editors of documents to team members with logins\n",
    "* Lightweight markup languages  \n",
    "    https://en.wikipedia.org/wiki/Lightweight_markup_language\n",
    "    \n",
    "    * reStructuredText and Markdown seem to be most popular\n",
    "    * Both support inline LaTex for creating nice formatted equations\n",
    "    * Both are used by popular document creation tools\n",
    "    * Markdown\n",
    "        * Pros: simplest language, easiest to learn\n",
    "        * Cons: no standard, many variants\n",
    "    * reStructuredText\n",
    "        * Pros: \n",
    "            * good tradeoff between simple and easy to use versus flexibility\n",
    "            * there is a standard\n",
    "                * new features are added via extensions (of which there are many)\n",
    "        * Cons: hard to find any, but definitely not as easy to use as Markdown\n",
    "* Documentation creation tools  \n",
    "    https://en.wikipedia.org/wiki/Comparison_of_documentation_generators\n",
    "    \n",
    "    * Doxygen  \n",
    "        http://www.stack.nl/~dimitri/doxygen/\n",
    "        \n",
    "        * Source is embedded in C++ code\n",
    "        * Can create html, man pages and API references\n",
    "        * Not clear how to get to \n",
    "    * Jekyll  \n",
    "        https://jekyllrb.com/\n",
    "        \n",
    "        * Used by github pages\n",
    "            * Can be shut off if guthub pages is given a ready to use format such as html\n",
    "        * Reads Markdown, Textile or Liquid\n",
    "        * Ruby based\n",
    "        * Can create html, but cannot create man pages\n",
    "    * Sphinx  \n",
    "        http://www.sphinx-doc.org/en/stable/index.html\n",
    "        \n",
    "        * Reads reStructuredText\n",
    "        * Python based\n",
    "        * Can create html and man pages\n",
    "        * Can create API references for Python, not clear if can do this for C++\n",
    "* Documentation publishing\n",
    "    * GitHub Pages  \n",
    "        https://pages.github.com/\n",
    "        \n",
    "        * Markdown is default, uses Jekyll to build html\n",
    "        * Can shut off Jekyll and read html directly\n",
    "    * ReadTheDocs  \n",
    "        https://readthedocs.org/\n",
    "        \n",
    "        * reStructuredText, uses Sphinx to build html\n",
    "            * Not clear if can process html directly\n",
    "\n",
    "    * There are paths from Sphinx to GitHub Pages  \n",
    "        https://daler.github.io/sphinxdoc-test/\n",
    "        \n",
    "        * Complicated to set up, but not so bad to use (after set up)\n",
    "        * Path\n",
    "            * Create reStructuredText source in /docs of branch master\n",
    "            * Use Sphinx to create html\n",
    "            * ReadTheDocs picks up commits on branch master\n",
    "            * Copy html into / of branch gh-pages\n",
    "                * First time: create an empty file (touch) called \".nojekyll\"\n",
    "                * This tells Jekyll (GitHub Pages) that you are supplying HTML directly\n",
    "            * GitHub Pages pickup up commits on branch gh-pages  \n",
    "            \n",
    "            * Pros: one source format\n",
    "            * Cons: checking generated files into gh-pages branch\n",
    "        * Perhaps GitHub Pages can process reStructuredText directly?\n",
    "        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notes, 1/25/18\n",
    "* Created ReadTheDocs business account\n",
    "    * readthedocs.org is the free \"social\" site\n",
    "    * readthedocs.com is the business site\n",
    "    * Business site has 30-day free trial\n",
    "* Still cannot see my private GitHub repositories\n",
    "    * Even creating a fork of UCAR/ufo doesn't work\n",
    "    * Cannot find how to make the private repositories visible\n",
    "    * Sent email to the readthedocs.com support desk"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notes, 1/29/18\n",
    "* ReadTheDocs support desk got back to me with instructions\n",
    "    * These did not work\n",
    "    * Sent error messages back to support person (Anthony), but haven't heard back yet\n",
    "* Jekyll \n",
    "\n",
    "    https://jekyllrb.com/\n",
    "    \n",
    "    https://programminghistorian.org/lessons/building-static-sites-with-jekyll-github-pages\n",
    "    \n",
    "    * Downloaded onto my iMac\n",
    "        * gem install jekyll\n",
    "    * Tried following:\n",
    "        * pandoc --from=rst --to=markdown_strict -o file.md file.rst\n",
    "            * Doesn't quite work - won't translate the block LaTex commands correctly\n",
    "            * Tried all of the markdown output (gfm, markdown, markdown_github, markdown_mmd, markdown_phpextra) and markdown_strict seems to work the best.\n",
    "            * Block LaTex doesn't translate\n",
    "            * Table of contents don't translate\n",
    "            * Index mechanism doesn't translate\n",
    "        * Put the resultant .md files in ~/projects/jekyll\n",
    "        * jekyll build --verbose\n",
    "            * In order for .md to be converted to .html, you need to add the following lines to the beginning of every .md file:\n",
    "            ```\n",
    "                 ---\n",
    "                 markdown: kramdown\n",
    "                 ---\n",
    "            ```\n",
    "                \n",
    "            * This  tell jekyll to convert the markdown to html using the \"kramdown\" filter\n",
    "    * Results in html that looks like man pages\n",
    "    * Cannot get themes working\n",
    "        * This should make for nicer formatting on web pages\n",
    "        * Tried doing: jekyll new ~/projects/jekyll/tryit\n",
    "        * This uses \"minima\" theme by default which is the man page looking theme\n",
    "        * Tried to install jekyll-theme-slate, but builds break because I'm missing libraries on my iMac\n",
    "    * Looks like Jekyll is geared toward creating/managing a blog\n",
    "        * This is a bit overkill for what we want (web site creation for documentation)\n",
    "    * Jekyll works with GitHub and Travis CI\n",
    "    * Jekyll's markdown language is kramdown  \n",
    "        https://kramdown.gettalong.org/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notes, 1/30/18\n",
    "* Decided to continue investigation\n",
    "    * Purchase the Basic business version of ReadTheDocs\n",
    "    * Define flows for:\n",
    "        * Private, development of docs\n",
    "        * Public, release of docs\n",
    "    * Get a path for Doxygen\n",
    "        * Breathe is an extension to Sphinx that allows reading Doxygen XML  \n",
    "        \n",
    "        https://github.com/michaeljones/breathe\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notes, 2/12/18\n",
    "\n",
    "* Sent an email to proservices@readthedocs.com asking about educational discounts\n",
    "* Once above question is answered (and we need to pay) will get a credit card to initiate the subscription\n",
    "* Connect the Basic business account to our new JCSDA GitHub account"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notes, 2/21/18\n",
    "\n",
    "## ReadTheDocs Business\n",
    "\n",
    "* readthedocs.com\n",
    "\n",
    "* Accounts and Organizations are separate entities\n",
    "    * An organization holds a collection of users\n",
    "    * Each user creates their own account\n",
    "    * Owners of an organization can invite users\n",
    "\n",
    "* Subscription is for an organization\n",
    "    * Up to 50 individual users\n",
    "    * Add a user to the organization --> subscription covers the user account\n",
    "\n",
    "* Delete an account\n",
    "    * On readthedocs.org (free site), there is a Delete button in the Settings for an account\n",
    "    * The button is missing in readthedocs.com (business site) but the function is there\n",
    "        * Go to account --> Settings\n",
    "        * In the URL, replace \"edit\" with \"delete\"\n",
    "        * Fill in form and hit delete\n",
    "\n",
    "* For JEDI\n",
    "    * Create individual users with our names\n",
    "        * So we know who each user is\n",
    "    * Created 'jcsda' organization\n",
    "        * Add users to 'jcsda'\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notes, 3/23/18\n",
    "\n",
    "## ReadTheDocs\n",
    "\n",
    "### To get access to a private GitHub repository\n",
    "* Import manually\n",
    "    * There is no button for importing manually on readthedocs.com\n",
    "        * It might work to enter the URL: https://readthedocs.com/dashboard/import/manual/\n",
    "    * If the URL doesn't work:\n",
    "        * Select a public repository to import\n",
    "        * When form comes up with name and URL, change these to the desired private repository\n",
    "* For the URL, use: git@github.com:JCSDA/jedi-docs\n",
    "* If the connection fails:\n",
    "    * Add the ReadTheDocs SSH key to the GitHub private repository\n",
    "    * Add the ReadTheDocs webhook to the GitHub private repository\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "jupyter": {
     "outputs_hidden": true
    }
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}