Getting Started with Documentation
Which branch to use?
Please use the mkdocs
branch to add/edit your documentation according to the guidelines detailed in this page. Once you are done with your edits, please submit a Pull Request (PR) to get your changes reviewed and merged to the master branch.
For PRs that include documentation changes
At the beginning of the PR, please add instructions on how one could compile the documentation and what pages should be reviewed. For example, these instructions could include the following:
- Checkout the
mkdocs
branch - Run
mkdocs serve
from the root directory (containing mkdocs.yml) - Open and review
path/to/edited-or-added-md-files
See the below discussion:
how can I look at the compiled version of these docs? (you might simply direct me to the place where this is explained in the docs) You can find this link in the main readme.
Please visit ShapeWorks website for more information.
I can open the individual .md files, but can't really give a final review until I've seen it in action. I think the only way you can see it in action is to checkout the branch and run mkdocs serve. These changes won't be reflected in the compiled version (i.e., gh-pages branch) till it is merged to master. @akenmorris ? I think it's completely reasonable to check out the branch and run mkdocs serve then browse to localhost:8000. I recommend explaining this right at the top of the pull request so people don't have to dig through the developer docs to remember the command every time they want to thoroughly review the updates.
Naming and Organization
Where are the documentation files?
ShapeWorks documentation is written using Markdown, a text layout language that enables simple formatting for section headers, code samples, weblinks, and images, yet is still readable as plain text. All documentation markdown files are located in the docs/
folder. Documentation settings are configured by using the mkdocs.yml
configuration file in the ShapeWorks directory.
Naming convention
To maintain consistency, please use lower-case letters and dashes for your markdown files, e.g., fixed-domain-ellipsoid.md
.
Docs organization
ShapeWorks documentation is organized into main sections (e.g., "Getting Started", "Use Cases", ... etc), which map to subfolders in the docs/
folder (e.g., "getting-started", "use-cases", ... etc) and images used in their markdown files are located in the corresponding subfolders in the docs/img
folder.
Adding Call-outs
We are now using the Admonition extension to include side content that is minimally disruptive to the document flow. It is also very useful to a reader's draw attention. Below are some examples.
To add a note block with a title, use the following markdown syntax.
!!! note "Title of the note"
Here is a note to keep in mind.
It will render as follows.
Title of the note
Here is a note to keep in mind.
You can also add a note without a title.
!!! note
This is a note without a title. This also applies to other call-outs.
It will render as follows.
Note
This is a note without a title
To make a note (or any call-out collapsable, use ???
as follows.
??? note
This is a collapsable note without a title. This also applies to other call-outs.
It will render as follows.
Note
This is a collapsable note without a title. This also applies to other call-outs.
To add a danger block with a title, use the following markdown syntax.
!!! danger "Don't try this at home"
Seriously don't try this; this is a dangerous step to take.
It will render as follows.
Don't try this at home
Seriously don't try this; this is a dangerous step to take.
To add an important block without a title, use the following markdown syntax.
!!! important
This is an admonition box without a title.
It will render as follows.
Important
This is an admonition box without a title.
Locally Building Documentation
To see local changes to documentation in realtime, cd
to where source documentation (i.e., mkdocs.yml
) is maintained and run the following command:
mkdocs serve
This command builds markdown files into HTML and starts a development server to browse the documentation.
Open up http://127.0.0.1:8000/
in your favorite browser to see the documentation. Changes you make to the markdown files are automatically rebuilt.
Deploying on GitHub Pages
As ShapeWorks is hosted on GitHub, we use GitHub Pages to host the documentation for ShapeWorks.
We use Project Pages sites for documentation deployment. The site files are deployed to the gh-pages
branch within the ShapeWorks repository.
To generate static HTML files for the markdown files, checkout the branch where source documentation (mkdocs.yml
) is maintained and run the following command:
mkdocs gh-deploy
Using this command, MkDocs builds the project documentation and uses the ghp-import tool to commit them to the gh-pages branch and push the gh-pages branch to GitHub. All behind the scenes ...
Danger
Running mkdocs gh-deploy
will update the documentation seen by everyone on GitHub. It is recommented that deployed documentation on GitHub should be synced with documentation in the master
branch.
Important
To deploy the documentation associated with software releases, please use the following command.
mkdocs gh-deploy -m "Release Number"
Use mkdocs gh-deploy --clean
to start a fresh deployment.
Use mkdocs gh-deploy --help
for a full list of options available for the gh-deploy command.
Take care when you deploy
You can not review the built site before pushing it to GitHub. To verify any changes you made locally to the documentation, please use mkdocs build
or mkdocs serve
.
Do not edit gh-pages
Never manually edit files on the gh-pages
branch because you will lose your work the next time you run the gh-deploy
command.
Contributing to Documentation
Important
If you added a new markdown file to docs/
, please make sure to include it in it relevant section in mkdocs.yml
to make it accessible.
We use GitHub to keep track of issues pertaining to ShapeWorks documentation. For an internal list of todos, which will be turned to issues, visit Documentation ToDo List.
Inserting Videos in Documentation
Request on GitHub for your video to be uploaded to the SCI ShapeWorks server.
Insert it in the markdown file using <p><video src="https://sci.utah.edu/~shapeworks/doc-resources/mp4s/video.mp4" autoplay muted loop controls style="width:100%"></p>
.
Where are the videos stored?
On SCI servers, at /usr/sci/www/shapeworks/doc-resources/mp4s/
.
Auto-generating ShapeWorks Commands Documentation
The DocumentationUtils
package in Python
has APIs for auto-documenting command-line tools and to-come-soon python APIs. We use the docs
folder to save the generated documentation.
To generate documentation for the shapeworks
commands, first be sure to run conda_install.sh
as described in How to Build ShapeWorks from Source? to install DocumentationUtils
.
Then, make sure that the shapeworks
command is in your path (set PATH=/path/to/shapeworks:$PATH
), then use Python to run the following command:
$ python Python/RunShapeWorksAutoDoc.py --md_filename docs/tools/ShapeWorksCommands.md
Parameters:
md_filename
is the markdown file name for the documentation file to be generated