HPQC Labs
1. Install TeX Live and go through the installation process, making sure that the install TeXworks front end box is checked when you get to the page where you choose the installation root.
2. Next, install Git Bash so that you can download the repository easily onto your computer. After this, launch the program and run the following lines to set up your account's default identity:
After this you’ll want to set up the directory which you will clone the Book about Quadratization to using:
For example, in order to set your directory to a folder named “test” on your desktop you would type the following:
Once this is done all you need to do is clone the repository using the following line:
3. With the repository now downloaded to your computer, open TeXworks and open up the Book_about_Quadratization.tex file from the repository, and build it by pressing the green play button in the top left.
Now that this has been done, you should notice that the pdf is working besides the missing bibliography and references. To fix this, open up the BookAboutQuadratizationNotes file (you’ll only see it listed by changing the file type to all files when opening) and build it. Once the console outputs some text press the stop sign in the top left and close out of the file. Go back to the main .tex file and by building the file once more you should see that everything is now working and ready for you to make your edits.
1. Once you have made changes to a file and you wish to commit the change, begin by opening Git Bash and navigating to the directory in which you cloned the Book_about_Quadratization repository.
For example, if I cloned the repository to a folder called “Test” on my desktop I would enter the following (using tab will autofill to make things easy):
2. Next you’ll want to add the files you’ve updated (In most cases this will just be the book .tex and .pdf files). You can do this by entering the following lines:
Then to make a commit enter the following line:
Finally, to push your commit, enter the following and everything should be updated:
In some cases, the main page will be updated prior to your commit. With files that have been altered locally, you want to avoid pushing your commit as you may overwrite someones work, and you want to avoid merging the main file with your local repository, so you don't overwrite the work you have done.
To get around this, you will want to use the stash feature in git bash.
1. First you will want to use the following code to save your local changes to the stash and revert whatever files were modified to their original state.
2. Next you will use the pull function to get your local repository back up to date with the main repository.
3. Finally to merge the additions you have made back into the newly update repository, use the following command:
Additional Note
In some cases conflicts may appear when you are attempting to use git stash pop with the recently merged content.
When this happens, you will need to manually go through and resolve these within your given application.
In the case of Visual Studio Code, the file that contains conflicts will be indicated, and the exact place in the code, highlighted.
It will then offer the user the choice to accept the current changes (that were there prior to the pull), accept the new changes (after the pull), or accept both.
Additionally there is a button to compare the code in each to see exactly what is being altered.
After the conflicts have been dealt with, it should be safe to proceed with the steps above in order to commit your work.
1. Follow the instructions here to install Sphinx. Use the directions that match the operating system you use.
2. In the command line, change your current directory to your project’s directory using the ‘cd’ command.
3. Run ‘sphinx-quickstart’ in your project’s directory and fill in the project’s information. For ‘Project name’ and ‘Author name(s)’, fill in the appropriate information you want to put. Otherwise, use the default settings (which are in the [] of each setting that has a default) by clicking Enter.
4. Open the conf.py file that was created in the previous step. It should be located in your project’s directory. Uncomment the lines (which should be lines 13-15):
5. Change the line “sys.path.insert(0, os.path.abspath('.'))” so that the pathway leads to where your project’s modules are located. Remember that the pathway is relative to your current project directory.
For example, if your modules are in a folder called, “yourModules”, which is located in your project directory, “yourProject”, then change the line to be:
6. In line 30 of conf.py, add ‘sphinx.ext.autodoc’ (include the ‘’) to “extensions”.
7. In the command line (the current directory as the project’s directory), run the ‘sphinx-apidoc’ command using the format:
For example, if the output directory is called “yourSource” and the module directory is called, “yourModules”, run:
The output directory will be where your .rst files will appear, and these .rst files will contain the autodoc directives that will generate your documentation.
8. Run ‘make html’. The HTML files can be found in the folder ‘_build’. If you get “WARNING: document isn't included in any toctree”, you can fix this by going into index.rst (located in your project directory) and adding modules.rst:
Optional: Update your theme by going into the conf.py file and changing the variable “html_theme”. The default theme will be “alabaster”.
1. Install doxygen. On Linux you can run sudo apt-get install doxygen, Windows and MacOS users can download the binaries> from here.
2. On Linux just run the command doxygen -g (in the folder where the code is) to create a configuration file called Doxyfile, then run doxygen Doxyfile to generate the documentation. Open doxywizard. At the top of the doxywizard page, under “Specify the working directory from which doxygen will run”, select the pathway to the project you want to document.
3. Under the “Wizard” tab, set the Project name, the source code directory, and the destination directory. The source code directory is where your modules will be located, and the destination directory is where the generated documentation will be created.
4. Under “Topics” in the “Wizard” tab, select Mode. Under “Select the desired extraction mode”, select “All Entities”. Under “Select programming language to optimize the results for”, pick the coding language that fits the code you are documenting.
Optional: If your documentation includes any LaTeX equations, under the “Expert” tab and in the Topic “HTML”, check the “USE_MATHJAX” box.
6. Under the “Run” tab, click “Run doxygen”. Then, click “Show HTML output” to view the generated documentation.
© HPQC Labs. All rights reserved.