GitHub Pages Documentation
The Graphitti team uses GitHub pages as a way to publish documentation of the system and it’s surrounding tools. This helps in making developing and using the Graphitti system more accessible.
Editing GitHub Pages
As with all other development on the Graphitti repository, please follow our contributing guide. Do not edit the gh-pages or master branch directly.
When making edits and changes to the GitHub Pages, you’ll create a new feature branch from the master branch, for a specified issue within the repository’s issue tab. Once the issue and branch have been created, you are ready to start making your edits to the pages.
We use markdown files in order to render our documentation in a web browser. These files follow a relatively simple syntax of which a guide can be found here for.
Once you’ve completed your edits and changes, commit them to the branch and obtain approval for merger. The changes will not be visible from the gh-pages branch until the first of the month unless you use the publish-gh-pages.yml script which can manually publish the documentation for you. Once merged though, the changes should be seen in the master branch. Find more information on these GitHub Actions here and here.
What is the gh-pages Branch?
This has to do with how the documents for the GitHub Pages are published. When you make changes and merge them into the master branch, you’ll notice those changes don’t immediately show up. This is due to the fact that the GitHub action that takes care of the publication is only activated at the first of every month. Or, you can manually activate it by using the publish-gh-pages.yml workflow in the actions tab.
When this publication occurs, all the files within the docs folder are pushed into the gh-pages branch. This branch then becomes the documentation published to the GitHub Pages site. We do this for 2 reasons:
- To keep from cluttering the commit history of the master branch along with just general clutter within the master branch files.
- When the gh-pages branch is published, it’s done so as an orphan which means that it has no commit history thus keeping itself uncluttered.
You can find more on the automation of the publication by navigating to the GitHub Actions page.
Folder Structure
All documents used for our pages reside in the docs folder within the Graphitti repo.
The Developer folder is used for documentation that deals with documenting systems for developers of Graphitti.
The Doxygen folder is used for documentation that refers to the Doxygen system.
The images folder is used for any images that are pulled in from developers ie. not images generated by the plantUML files or other UML files. Those UML files should be found and stored in the Developer/UML folder.
The Testing folder is used for documentation that refers to testing the Graphitti system.
The User folder is used for documentation that general Graphitti users. Anyone who is using the graphitti system and needs to know how to download or use it should go to the User folder for help.
Tips When Editing
- Try to keep new documentation files as object oriented as possible
- Think about whether you actually need a new markdown file or can your documentation be appended/attached to an existing file
- Try to have your headings and formatting follow a consistent pattern
- Determine if you need a new heading or can your documentation be attached/appended to another heading within the same file
- Make sure to have a way to preview the markdown files you are making changes to
- VSCode has some markdown preview enhancements provided as extensions
- There should also be a built in preview functionality in the upper right hand corner of your VSCode window
- VSCode has a plantUML plug-in to help view plantUML files as images
« Go back to the Developer Documentation page