4.4. Hosting the API Documentation Website

Generating the API documentation is great, but seeing it is even better. You can use the steps provided below to host the generated website using your Odin account. Alternative approaches to the explicit instructions provided below are explored in the FAQ section towards the end of this tutorial.

1. Ensure that you have a public_html directory in your home directory. If the ~/public_html directory does not exist, you should create it. The purpose of this directory on Odin (and on many systems) is to support user websites, which will be illustrated in the following steps. We will focus on API Documentation websites in this course but you could build and host a personal “about me” page using Odin. Please note that you are fully responsible for anything that you host through your Odin website.

2. To make our documentation publicly available on the web, we will set up a symbolic link to the doc directory you created in the previous steps. You can think of a symbolic link as a shortcut to those files. The symbolic link will need to be placed in the ~/public_html folder but the doc directory you created will not move.

   The syntax for the command to create a symbolic link is:

   Listing 4.1 This is not a working command - it is the high level syntax

   ln -s <absolute path to the doc directory> <relative path to the link being created>
   

   Notice that the first path must be an absolute path and that the second path can be a relative path. For example, if I were running the ln command from within the cs1302-javadoc directory that contains my doc folder, my command might look something like this:

   Listing 4.2 This is an example using placeholder directories. It will not work unless modified.

   ln -s /absolute/path/to/cs1302-javadoc/doc ~/public_html/cs1302-javadoc-doc
   

   where /absolute/path/to/cs1302-javadoc/doc is replaced with the real absolute path to doc and cs1302-javadoc-doc is the name of the symbolic link being created. The absolute path required will depend on your username and the name of the link can be anything you like (although we generally recommend using the same names we use in the tutorial). When typing out the absolute path, be sure to use tab completion!

   Recommended Shortcut (avoid typing the full absolute path)

   If you want to avoid typing the absolute path every time, you can try the command below. However, for this command to work properly, it must be executed from the directory that contains the doc directory. In this example, the command must be run from the cs1302-javadoc directory.

   Listing 4.3 This command will only work if executed within cs1302-javadoc (the parent folder of doc).

   ln -s $(pwd)/doc ~/public_html/cs1302-javadoc-doc
   

   Understanding the Command

   As previously stated, the ln command requires the absolute path to our link’s target (in this case, doc). Since our intended target is in the current directory, we know that its absolute path is the same as the absolute path of the current directory followed by / followed by the name of our target. We could manually figure out the desired path with the help of pwd or we can use $(pwd), as seen above, to fill in the output of pwd instead. You could also type out the entire absolute path but that would be tedious and error-prone. If you type out the full path, be sure to use tab completion!

   In this scenario, the symbolic link is called cs1302-javadoc-doc. You can see it if you change into your public_html directory and perform an ls -l. The entry for cs1302-javadoc-doc in the long listing indicates that the file is a symbolic link in two different ways: i) an l is prefixed in the mode instead of - or d; and ii) the filename lists an arrow pointing to the link target.

3. Navigate to the following URL in your web browser, replacing user with your Odin username in the URL below (leave the ~). If you have any trouble viewing your website, see the next section for troubleshooting tips:

   Listing 4.4 Replace user with your myID and enter this into your favorite browser

   https://webwork.cs.uga.edu/~user/cs1302-javadoc-doc/
   

   Congratulations! If you followed the steps correctly, then you should see the API documentation website that you generated earlier. If your website did not show up, move on to the next section for some Troubleshooting Tips.

   Does this website look similar to any other websites that you may have visited?