From acc596e92555dd5605202fe8eefda68a182d66b2 Mon Sep 17 00:00:00 2001
From: digehode <digehode@googlemail.com>
Date: Tue, 21 Jul 2020 13:45:51 +0100
Subject: [PATCH] Change of plan. Sphinx was too heavy

---
 .gitignore        |  1 +
 Makefile          |  4 ++--
 README.md         | 24 +++++++++++++++++-------
 requirements.txt  |  2 +-
 src/transcoder.py |  5 ++++-
 5 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/.gitignore b/.gitignore
index 14e212a..045d7b9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -103,3 +103,4 @@ venv.bak/
 # mypy
 .mypy_cache/
 *~
+/transcoder.m.html
diff --git a/Makefile b/Makefile
index e43f367..4ed25b9 100644
--- a/Makefile
+++ b/Makefile
@@ -7,8 +7,8 @@ prereqs: venvcheck FORCE
 venv: FORCE
 	python3 -m venv venv
 
-# docserve:
-# 	pydoc -p 5555
+docs:
+	pdoc --html ./src/transcoder.py --overwrite
 
 venvcheck:
 ifeq ($(INVENV),)
diff --git a/README.md b/README.md
index cea4de0..b9bb530 100644
--- a/README.md
+++ b/README.md
@@ -106,9 +106,9 @@ will be classes, functions, modules and the data passed to or stored
 by these.
 
 To view the documentation for the file `transcoder.py`, from the
-directory in which this readme is located, you can execute `pydoc
+directory in which this readme is located, you can execute `pdoc
 ./src/transcoder.py`. It's just like a Linux `man` page.  Press Q to
-quit.
+quit if it goes over one screen.
 
 You should document your code as you write. Use comments for people
 that need to know what your code does in order to modify or maintain
@@ -118,11 +118,18 @@ people calling on your classes and functions in their own code.
 
 ### Prettier documentation
 
-To view the documentation in your browser, you have some options.  The
-basic methods are: generate HTML versions of your documentation and
-store it to be viewed in your browser *or* use the built-in web server
-that `pydoc` contains to generate your documentation on the fly and
-point your browser at it.
+To view the documentation in your browser, you can output the content
+as HTML and view it.  To do this, use `pdoc --html
+./src/transcoder.py`, which will generate a file called
+`transcoder.m.html` that you can view in your browser.
+
+To regenerate, you need to add the `--overwrite` option to the command
+to tell pdoc to overwrite the existing file.
+
+We've included a `Makefile` which is a special kind of file that the
+'make' command reads. We won't get into the details of `make` in this
+project, but what we have provided means that you can create the documentation. Just use `make
+docs`. 
 
 TODO: this bit
 
@@ -213,3 +220,6 @@ TODO:
  - Put proper pydoc generation in and fill in all docstrings
  - Write bit about cloning repo
  - Write tests for asASCII (but not give the function)
+
+<!--  LocalWords:  pdoc
+ -->
diff --git a/requirements.txt b/requirements.txt
index 43cd3ab..eae2427 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,4 +1,4 @@
 wheel
 colored
 pytest
-sphinx
+pdoc
diff --git a/src/transcoder.py b/src/transcoder.py
index 9146464..2b87551 100755
--- a/src/transcoder.py
+++ b/src/transcoder.py
@@ -2,9 +2,12 @@
 """ Software and functions to convert from arbitrary strings to various representations of the individual characters """
 import colored
 
-#TODO: Docstrings
+
 
 def asHex(data):
+    """ Return a string containing the hexadecimal representation of the input string.  For example, with the input "ABC", the function will return "0x41 0x42 0x43"
+    """
+    
     #Start with an empty string
     output=""