-
Notifications
You must be signed in to change notification settings - Fork 0
__README
The ./docs
folder is the root documentation folder for this repository.
Subfolders: internal and public.
Pages and images from docs/internal
will be published in This repo wiki after running the script (described in Wiki info below).
Pages and images from docs/public
will be published to our Public docs when a PR is merged to the main
branch - by automation.
The subfolder docs/_wiki
is a clone of the repo's wiki repository, which appears as a submodule in the main repo (see .gitmodules
)
-
Clone repo with submodule pulled (if already in master):
git clone --recurse-submodules https://github.com/msupply-foundation/conforma-web-app.git
-
Clone repo with submodule in specific branch:
git clone --recurse-submodules -b <branch_name> https://github.com/msupply-foundation/conforma-web-app.git
-
Then Init and pull submodule folder:
git submodule update --init
The wiki contents is essentially exactly the same as the docs/internal
folder. However, the way the wiki software handles internal links when online is different, and all pages are presented at the wiki root level, which means some relative links need to be adjusted accordingly.
In order to update the wiki from the current internal documentation state, and push the wiki docs online, simply run:
yarn push_docs
(This runs a python script to convert the wiki docs -- it can be configured by adjusting the variables at the top of ./utils/convert_docs_to_wiki.py
)
-
Page (
.md
) files should have hyphens (-
) instead of spaces, e.g.Database-Schema.md
, which will appear on the wiki with the page title Database Schema. -
While pages can be organised into subfolders within the
documentation
folder, when published to the wiki, they appear with a "flat" structure -- i.e. they'll appear with the URL/wiki/<Page-name>
regardless of internal folder nesting. Therefore, proper linking (including a well-maintained Contents) is the best way to manage wiki structure. -
Try to keep image files in the
images
folder and prefix them with the name of the page they appear (in lower case). Also, try to remove images that are no longer referenced to avoid build-up of orphaned media files. -
Only push documentation to the wiki from the
master
branch. This ensures that all documentation updates have been through PR and merged before being pushed "live". -
Docs should only go "one-way" -- from the subfolder
docs/internal
to the wiki, not the other way. So please don't edit the wiki directly on Github, or else you risk any changes being over-written the next time the docs folder is "published".
Powered by mSupply