seitime-frappe/frappe/docs/user/en/guides/app-development/generating-docs.md

Generating Documentation Website for your App

Frappe version 6.7 onwards includes a full-blown documentation generator so that you can easily create a website for your app that has both user docs and developers docs (auto-generated). These pages are generated as static HTML pages so that you can add them as GitHub pages.

Writing Docs

1. Setting up docs

1.1. Setup docs.py

The first step is to setup the docs folder. For that you must create a new file in your app config/docs.py if it is not auto-generated. In your docs.py file, add the following module properties.

source_link = "https://github.com/[orgname]/[reponame]"
docs_base_url = "https://[orgname].github.io/[reponame]"
headline = "This is what my app does"
sub_heading = "Slightly more details with key features"
long_description = """(long description in markdown)"""

def get_context(context):
    # optional settings

    # context.brand_html = 'Brand info on the top left'
    # context.favicon = 'path to favicon'
    #
    # context.top_bar_items = [
    #   {"label": "About", "url": context.docs_base_url + "/about"},
    # ]

	pass

1.2. Generate /docs

To generate the docs for the current version, go to the command line and write

bench --site [site] build-docs [appname]

If you want to maintain versions of your docs, then you can add a version number instead of current

This will create a /docs folder in your app.

2. Add User Documentation

To add user documentation, add folders and pages in your /docs/user folder in the same way you would build a website pages in the www folder.

Some quick tips:

1. Add your pages as .md or .html pages
2. Optionally add .css files with the same name that will be automatically served
3. Add index by adding {index}

3. Linking

While linking make sure you add {{ docs_base_url }} to all your links.

{% raw %}<a href="{{ docs_base_url }}/user/link/to/page.html">Link Description</a>{% endraw %}

4. Adding Images

You can add images in the /docs/assets folder. You can add links to the images as follows:

{% raw %}<img src="{{ docs_base_url }}/assets/img/my-img/gif" class="screenshot">{% endraw %}

---

Setting up output docs

1. Create a /docs folder in your bench, parallel to your /sites folder. e.g. /frappe-bench/docs
2. Copy the repo of your app to the docs folder. e.g. cp -R apps/myapp docs/myapp (you can also clone it here using git clone).
3. Go to your docs folder cd docs/myapp
4. Checkout the gh-pages branch git checkout --orphan gh-pages
5. Clean everything git rm -rf .

Note > The branch name gh-pages is only if you are using GitHub. If you are hosting this on any other static file server, can just skip this and just create your docs folder for your app like docs/myapp

Putting it all together:

mkdir docs
cp -R apps/myapp docs/myapp
cd docs/myapp
git checkout --orphan gh-pages
git rm -rf .

---

Viewing Locally

To test your docs locally, add a --local option to the build-docs command.

bench --site [site] build-docs [appname] --local

Then it will build urls so that you can view these files locally. To view them locally in your browser, you can use the Python SimpleHTTPServer

Run this from your docs/myapp folder:

python -m SimpleHTTPServer 8080

---

Publishing to GitHub Pages

To publish your docs on GitHub pages, you will have to create an empty and orphan branch in your repository called gh-pages and write yours there

Now go back to your bench folder and write these docs to this branch. For example if your path to the gh-pages repo is docs/reponame

bench --site [site] build-docs [appname]

To check your documentation online go to: https://[orgname].github.io/[reponame]