Branch's public documentation
Clone or download
Latest commit a2b282e Jan 18, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci remove docker image building Jan 11, 2019
lib/mkdocs-material set anonymize ip Jun 1, 2018
src Merge pull request #966 from BranchMetrics/INTENG-4560 Jan 18, 2019
.gitignore fix: forever and ever no node_modules in git Mar 6, 2018
README.md Update README.md Nov 1, 2018
mkdocs.yml DOCS-425 Jan 18, 2019
requirements.txt ...but also need requests Oct 23, 2018

README.md

Branch Docs

Repository for Branch's public documentation https://docs.branch.io

Goal

  • Get partners up and running as fast as possible

    • Educate with a single best path (do not list all the override methods)

    • Educate with working code examples

    • Bullet point key points, procedures, and steps to promote progression

    • Use shorter sentences with simpler words (3rd grade) to prevent ambiguity

    • Trigger action by beginning each sentence with a verb

    • Write in the viewpoint of the user's wants, not what Branch wants

    • Keep it simple (KISS) (1 -> 2 -> 3)

    • Don't repeat yourself (DRY) (this can be found here)

  • Answer any question a partner will have

    • Make sure you answer why, what, how (example) with each section

Environment

  • Code

    git clone git@github.com:branchmetrics/docs.git
    cd docs
  • Dependencies

    pip install -r requirements.txt
  • Develop

    mkdocs serve
    open http://127.0.0.1:8000
  • Deploy

    • Merge pull request into master
    • Create new pull request from master
    • Merge pull request from master into production on release days
  • Production

Contributing

  • Folders

    • Must be lowercase and hyphened
  • Content

    • Bullets and sections must have double new line spacing in between

    • Indention is 4 spaces

    • Search works best when content is not duplicated

    • Only add periods if more than one sentence

  • Style

    • Titles # Title

    • Sections ## Section

    • Category - #### Section

    • Content - content

  • Code Tabs

    • Tabbed sections *title*, code, *title*, code
  • Navigation

    • Different page click [here](/pages/apps/ios/) (must have trailing slash)

    • Different page anchor click [here](/pages/apps/ios/#configure-bundle-identifier)

    • Same page anchor click [here](#configure-bundle-identifier)

  • Tips, notes, warnings etc.

  • Code Modals

    • Complete [Integrate your app](#dialog-code?ios=create-deep-link&android=install-branch)

    • Complete [Integrate your app](#dialog-code)

    • ios, android, cordova, mparticleAndroid, mparticleIos, titanium, reactNative, unity, xamarin

  • Images

    • Content pages are kept in the img/pages

    • Example images used in ingredients are kept in the img/ingredients

    • ![image](http://i.imgur.com/dyfhN0L.png)

  • Search

    • Hosted by Algolia Docsearch

    • Localhost scrapes production

    • Production is scraped once a day

    • Prevent search results by adding production url to stop_urls (config)

  • Redirection

    • Add <script>window.location = "/pages/dashboard/people-based-attribution"</script> to the top of the file

Additional

  • Resources

  • Mkdocs Local Deploy

    • not recommended

      mkdocs gh-deploy
  • Mkdocs Locally

  • Mkdocs Fix

    • remove mkdocs sudo rm -rf /usr/local/bin/mkdocs

    • remove mkdocs link rm -rf /Library/Python/2.7/site-packages/mkdocs.egg-link

    • remove pip rm -rf /Library/Python/2.7/site-packages

    • reinstall pip curl https://bootstrap.pypa.io/get-pip.py > a.py && chmod -x a.py && sudo ./a.py

    • reinstall dependencies

    • run develop

  • Mkdocs-Material Locally

    • readme http://squidfunk.github.io/mkdocs-material/customization/#theme-development

    • add to repo git subtree add --prefix lib/mkdocs-material https://github.com/squidfunk/mkdocs-material master --squash

    • update to repo git subtree pull --prefix lib/mkdocs-material https://github.com/squidfunk/mkdocs-material master --squash

    • test live update in /materials

    • prod code in /src

      • cd lib/mkdocs-material

      • yarn install

      • yarn build (will build /material, but fail on /site (this is okay))

    • updated files

      • lib/mkdocs-material/src/partials/footer.html

      • lib/mkdocs-material/src/partials/header.html

      • lib/mkdocs-material/src/partials/search.html

      • lib/mkdocs-material/src/partials/nav.html

      • lib/mkdocs-material/src/base.html

      • lib/mkdocs-material/src/assets/javascripts/application.js

      • lib/mkdocs-material/src/assets/images/favicon.png

  • Slow page render

    • The docs should load within 1400ms. If it takes 5000ms, please disable Ghostery (Google Analytics) and Adblocker (the docs have AB testing)
  • Missing search

    • Some ad blockers prevent the search from appearing