For a recent interview at LinkedIn, one of the tech writers there suggested I learn a little Sphinx. Sphinx is a documentation generator for the Python programming language.
I followed the steps to install Sphinx HERE. I got through the steps. However, I wanted more. For one thing, I was not sure if my Python was set up. And I wanted Python code to run, and into which I could put Sphinx commands to auto-generate API documentation (as I did using Javadoc during my stint at Hazelcast).
So I started a Lynda.com video class: Python 3 Essential Training. I installed the latest version of Eclipse (well, maybe I shoudl have used Xcode, but I needed to update my Eclipse anyhow). Then, in the section for Installing Python 3 and Eclipse for Mac, it asked me to find the Python interpreter. I had to type in the path to the interpreter instead of navigating to it. Why? Because the Python was in /usr/local/bin, and usr would not show up when I clicked Browse.
I followed the First Steps for Sphinx that show how to run sphinx-quickstart and generate some simple hello-world type documentation. I found that easy enough to read, like Markdown. But I also wanted to generate a little bit of API documentation. Like Javadoc.
I had the Lynda.com Python code for generating a Fibonacci sequence. I ran it and knew it worked. Then I found a YouTube video for using Sphinx to document python code. Even though I had already set up a Sphinx project with sphinx-quickstart, I ran through the steps again to create a cleaner project. I copied the Python project into that project folder. And I inserted a simple command: """Return a Fibonacci sequence.""" And I generated a Python code web page in my project. Yay! But I have more to learn (such as listing out al the parameters).
The lesson I learned: Although I can run through nice tutorial text steps, a video showing the steps make the process much clearer. As in, "Oh, so THAT'S what it looks like!"
I followed the steps to install Sphinx HERE. I got through the steps. However, I wanted more. For one thing, I was not sure if my Python was set up. And I wanted Python code to run, and into which I could put Sphinx commands to auto-generate API documentation (as I did using Javadoc during my stint at Hazelcast).
So I started a Lynda.com video class: Python 3 Essential Training. I installed the latest version of Eclipse (well, maybe I shoudl have used Xcode, but I needed to update my Eclipse anyhow). Then, in the section for Installing Python 3 and Eclipse for Mac, it asked me to find the Python interpreter. I had to type in the path to the interpreter instead of navigating to it. Why? Because the Python was in /usr/local/bin, and usr would not show up when I clicked Browse.
I followed the First Steps for Sphinx that show how to run sphinx-quickstart and generate some simple hello-world type documentation. I found that easy enough to read, like Markdown. But I also wanted to generate a little bit of API documentation. Like Javadoc.
I had the Lynda.com Python code for generating a Fibonacci sequence. I ran it and knew it worked. Then I found a YouTube video for using Sphinx to document python code. Even though I had already set up a Sphinx project with sphinx-quickstart, I ran through the steps again to create a cleaner project. I copied the Python project into that project folder. And I inserted a simple command: """Return a Fibonacci sequence.""" And I generated a Python code web page in my project. Yay! But I have more to learn (such as listing out al the parameters).
The lesson I learned: Although I can run through nice tutorial text steps, a video showing the steps make the process much clearer. As in, "Oh, so THAT'S what it looks like!"