ubports/docs.ubports.com

UBports Documentation

UBports Documentation Website

This is the repository for the UBports documentation website served at docs.ubports.com.

Contribution guidelines

You can find ways to contribute here. Please follow all of the guidelines on that page, else your contribution will not be accepted.

Build instructions

The documentation can be built by running ./build.sh in the root of this repository. The script will also create a virtual build environment in ~/ubportsdocsenv if none is present. After the build is complete, you can view the documentation by opening the html files in your favorite browser (eg. firefox _build/html/index.html).

Update translations

To update translation templates, run ./update-translations.sh in the root of this repository.

Build status

• English
• Catalan
• French
• German
• Italian
• Romanian
• Russian
• Turkish
• Spanish
• Simplified Chinese

docs.ubports.com's Issues

Document full list of available policy groups

App Development documents a few of the policy groups available to app developers, but we should really have an exhaustive list of policy groups (and the frameworks they belong to) somewhere.

Policy groups can be found in apparmor-easyprof-ubuntu

UserMetrics tutorial missed important points

Description

For the user metrics to work, there are 2 important points that should be mentioned in the document.

1. "usermetrics" policy must be added to the apparmor configuration file.
2. The property "name" MUST be provided as this is like the ID for storing the user metric data.

Ammends to BottomEdge Docs

• The example in the Detailed Description has Page.title property which is deprecated

• Add a warning with: If BottomEdge contentUrl is a Page without a header property, the BottomEdge behaves weird

Anbox documentation

Hi.

I'm not sure, if this is the right place to post this message. Please, feel free to redirect it to an adequate location.

---

I successfully installed Anbox on my OnePlus One phone. Thanks for this documentation:

http://docs.ubports.com/en/latest/userguide/dailyuse/anbox.html
https://github.com/ubports/docs.ubports.com/blob/master/userguide/dailyuse/anbox.rst

At one point, I stumbled because of the message: "no space left on device" A quick internet research led me to the solution: sudo mount -t tmpfs tmpfs /var/cache/apt/archives/ It would have been helpful to find this hint directly in the mentioned Anbox documentation.

Again, thanks to the community for UBports.

Update documentation for atom-build-clickable

The documentation
https://docs.ubports.com/en/latest/appdev/index.html
should include
https://ubports.com/blog/ubports-blog-1/post/clickable-for-atom-98

SortFilterModel Example Doesn't work

Testing the example of this section shows a blank window.

• Looks like sortCaseSensitivity doesn't work
• Used ListItems which is deprecated

This might be a replacement

import QtQuick 2.9
import Ubuntu.Components 1.3

MainView {
    width: units.gu(80)
    height: units.gu(40)

    ListModel {
        id: movies

        ListElement {
            title: "Esign"
            producer: "Chris Larkee"
        }

        ListElement {
            title: "Elephants Dream"
            producer: "Blender"
        }

        ListElement {
            title: "Big Buck Bunny"
            producer: "blender"
        }
    }

    SortFilterModel {
        id: sortedMovies
        model: movies

        sort {
            property: "title"
            order: Qt.DescendingOrder
        }

        filter {
            property: "producer"
            //Add i for case insensitive
            pattern: /Blender/i
        }
    }

    ListView {
        model: sortedMovies
        anchors.fill: parent
        delegate: ListItemLayout {
            title.text: model.title
            subtitle.text: model.producer
        }

        section {
            property: "title"
            criteria: ViewSection.FirstCharacter
            delegate: Text {
                text: i18n.tr(section)
            }
        }
    }
}

Documentation partially translated in French even if Weblate is at 100% complete

The French translation is complete at 100% on Weblate since a couple of months, but the Documentation is still partially translated.

Could you please refresh the Documentation with the latest version of the translations?

Thanks in advance.

Request - Adding more adb commands to the 'Shell access via adb' page

For example

adb push [source] [destination] – Pushes a file from your computer to your Ubuntu Touch device.
adb pull [destination] [source] – Pulls a file from your UT device to your computer – works like adb push, but in reverse.

adb shell – Gives you access to the Linux command-line shell on your device.
adb shell command – Runs the specified shell command on your device.

Wrong URL for supported devices

In https://docs.ubports.com/en/latest/userguide/install.html# the link for supported device is wrong (https://docs.ubports.com/en/latest/userguide/devices.ubports.com).

Should it be http://ubuntu-touch.io/devices or https://devices.ubports.com, I don't know which is best at reflect the current state of communication needs.

HTML5 RuntimeApi file system access

RuntimeApi
The RuntimeApi seems to lack information about some functions.

String getApplicationWritableLocation() Retrieves the fileystem location where the application is
allowed to write its data in.

There seems to be functionality to read/write to the file system but it is not documented how to access it.
https://api-docs.ubports.com/sdk/apps/html5/RuntimeApi/RuntimeApi.html

App developpement overview - quick start

Would be great to have a short overview.
What languages we can use, short introduction of click packaging format, apparmor, confinement constrains.
Links to 'hello-world' templates (i think brian is going to add start examples, kind of a clickable init ).

Desktop apps not supported on my nexus 5

In https://github.com/ubports/docs.ubports.com/blob/master/userguide/dailyuse/libertine.rst you say to download the Desktop Apps app, but the OpenStore says it is not supported on my Nexus 5 Ubuntu Touch 16.

Desktop applications section instructions is incomete, skips the installation instructions

I think the instructions on https://docs.ubports.com/en/latest/userguide/dailyuse/libertine.html are incomplete. It assumes libertine is already present and just tells you to install the scope. You need to follow instructions on https://wiki.ubuntu.com/Touch/Libertine first

I'm willing to make a pull request to

• add the instructions from https://wiki.ubuntu.com/Touch/Libertine
  Or
• add a link to https://wiki.ubuntu.com/Touch/Libertine

docs.ubports.com has a new Mascot

Ok... so not exactly what you had in mind? But (no pun intended) now that you are here I'd like to take this opportunity to let you know that UBports is recruiting writers to help with the documentation. If you like to write and are interested in helping UBports grow and prosper, then let us know!

Thanks!
UBdocs Teams

Update libertine documentation

The existing libertine documentation at http://docs.ubports.com/en/latest/userguide/dailyuse/libertine.html is not up-to-date, e.g. the app-scope doesn't have to be installed from the openstore anymore and containers can be created/managed from the settings in addition to the CLI.

Amends to 'Shell access via ssh' page

This line:
chown -R phablet.phablet /home/phablet/.ssh
needs to be changed to
chown -R phablet:phablet /home/phablet/.ssh

All Im suggesting here is to change the . to a :

App development, system software: missing information

http://docs.ubports.com/en/latest/appdev/system-software.html

If I follow the steps for "Building on the device itself" and enter
sudo apt-get build-dep address-book-app
I am told that
you must put some 'source' URIs in your sources.list

What are the correct sources to list?

Changes in docs don't sync with weblate

When something changes in the docs content it should be push to UBports Weblate for translation as quickly as possible. Now days go by.

Please add Simplified Chinese pot file

There is no simple Chinese option on the translation page, so we hope you can add the simplified Chinese option for translation.
Thanks.

Wi-fi broken after trying to follow the Android apps guide on Hammerhead

• Device: Hammerhead
• Channel: stable
• Build: OTA-15

Steps to reproduce

I followed the Android apps wiki guide after a fresh install of stable channel (OTA.15), Hammerhead (https://docs.ubports.com/en/latest/userguide/dailyuse/anbox.html).

Specifically, after:

wget http://cdimage.ubports.com/anbox-images/anbox-boot-$CODENAME.img
adb shell # connect from your host computer to your UT device
sudo reboot -f bootloader # 'adb shell' will exit after this command, the prompt will be back on your host
sudo fastboot flash $PARTITIONNAME anbox-boot-$CODENAME.img
sudo fastboot reboot
rm anbox-boot-$CODENAME.img
exit

when the phone rebooted, and I used the following commands:

adb shell # connect from your host computer to your UT device
sudo mount -o rw,remount /
sudo apt update

... I wasn't any more able to update the software. Looking at the Configuration panel there is no more evidence of any wifi connection (even the one I normally used before) ...

Update backup documentation

We should either create a script to facilitate backing up data (by copying /data/user-data, /data/system-data, and /data/android-data from recovery to another devices) or tell people how to do it themselves.

Systemdev section is not in Weblate

Recently I added the "systemdev" section of the documentation as a place for storing information about system components and working on them. This section is not yet added as a component in Weblate.

The POT file can be found at https://github.com/ubports/docs.ubports.com/blob/master/locales/pot/systemdev.pot

add description on github

and a link! Something like:

This is the repository for the Ubports documentation website served at http://docsubportscom.readthedocs.io/en/latest/

I tried Anbox on the Nexus 5

I saw that there is a hammerhead img http://cdimage.ubports.com/anbox-images/ and I decided to try it out.
While following this tutorial http://docs.ubports.com/en/latest/userguide/dailyuse/anbox.html?highlight=anbox I decided to use boot as my PARTITIONNAME (IDK which one is actually the right one) and hammerhead as my CODENAME. The end result is a device that is stuck at boot after I ran the sudo fastboot reboot command :) I'll have to reflash Ubuntu Touch on it again. What have I done wrong? Any help please?

Also why not provide the boot name for the rest of the devices since you already provide an image for them? Thanks.

edit: Apparently only this command didn't work sudo fastboot reboot and I just had to turn the phone off and back on. All the other steps were successful and Anbox worked nicely as well. Overall I'm satisfied with the results.

webapp-container

Update the supported commands in https://docs.ubports.com/en/latest/appdev/webapp/guide.html
For instance: webapp-container --open-external-url-in-overlay

Link to BQ E4.5 firmware download in «install.rst» is broken

BQ has remodeled its website recently, and now the link in https://github.com/ubports/docs.ubports.com/blob/master/userguide/install.rst pointing to http://www.mibqyyo.com/de-download/categorias/smartphones/aquaris-e-serie/aquaris-e4-5-ubuntu-edition/ gets a «Page not found» error.

The new BQ E4.5 download page is https://www.bq.com/en/support/aquaris-e4-5-ubuntu-edition/support-sheet but it seems that not all the necessary software is there.

For reference:

• Archived version of that linked page originally https://web.archive.org/web/20180122020727/http://www.mibqyyo.com/de-download/categorias/smartphones/aquaris-e-serie/aquaris-e4-5-ubuntu-edition
• The download firmware page (it's necessary to accept an EULA) https://web.archive.org/web/20180121014108/http://www.mibqyyo.com:80/descargas/categorias/aquaris-e4-5-ubuntu-edition

Generate POT files for Portuguese (PT)

Hi,

We need translate the docs.ubports.com but the files aren't on weblate and e we can't add them.

Thanks.

/user/ixavier/

After install clickable section incorrect

after installing clickable the command mentioned below and in this link doesn't work!

Let Clickable setup docker (it could ask for the sudo password): clickable setup

clickable setup
There is no builtin or custom command named "setup"

Move documents from old wiki

Some documents from the old wiki are very relevant and we should continue to use them (after reformatting them in ReStructuredText, of course).

The ones I see at first glance are:

• Install UBports
• Use ADB from Desktop
• *DAV synchronization
• Install 16.04
• Set up app development environment
• Set up app development environment in container
• Set up Cordova app development environment in container
• Writing a good bug report
• UBports Bug Trackers
• Release Channels
• How a UBports image is built
• Building libhybris
• Porting Information (And subpages)

Create a list of convergence enabled devices

There should be two lists, devices that support miracast and devices that support being plugged in.

Some ReadTheDocs builds are failing

Right now, our Catalan build is failing: https://readthedocs.org/projects/docsubportscom-catalan/builds/12108936/

But our English build is not: https://readthedocs.org/projects/docsubportscom/builds/12108281/

I've traced this back to the use of --use-feature 2020-resolver in our English build but not Catalan. This feature was recently enabled by ReadTheDocs on a random set of projects. readthedocs/readthedocs.org#7412

This leads to Sphinx 3.2.1 being installed on the English build while 1.8.5, the ReadTheDocs attempted forced version, on Catalan.

I'd prefer having the newer Sphinx since Rediraffe doesn't support Sphinx under 2.0. Specifying the newer Sphinx in our requirements.txt should do it, since ReadTheDocs allows it to override its own default packages.

Add landing pages

Start from a good foundation and build from there, I always say.

Before we start writing a bunch of documents, we should get our landing pages in place. These include our indexes for top-level categories and each subcategory under them.

• About (About UBports, documentation structure)
• User Guide
• Installation
• Daily Use
• Hacking (Fancy command line stuff, things that require writable root)
• Contribution
• Bug Reporting
• App Development
• OS Development
• Translation
• Documentation
• Monetary Support

See how these all fit together (since I can't nest them on GitHub) here.

[Typo] Clipboard, MimeDala -> MimeData

https://api-docs.ubports.com/sdk/apps/qml/Ubuntu.Components/Clipboard.html?highlight=MimeDala

remove references to oxide webview from ubports documentation.

The following section of Ubports documentation contains references to oxide web view. As the oxide is being removed as part of OTA-16.The following section might require changes. https://docs.ubports.com/en/latest/appdev/webapp/guide.html

Update github About section to include UBDocs telegram group details

Please add a link to the telegram UBDocs group so that it is easier for new users to reach the UBDocs team. Please find in attachment a screenshot of another repo for better understanding.

Add documentation on Dark Style preference

Add docs on the new preference (from a user perspective) when system-settings#166 has been implemented.

Add docs on the new preference (from a app developer perspective) with examples on how to switch the theme in the UITK and QQC2/Suru when ubuntu-ui-toolkit#39 has been implemented.

how much disk space needed to build Ubuntu Touch?

We didn't find if it's mentioned in the docs.

@sashakrava

add architecture overview page

For developpers newcomers, we should provide a quick overview of the architecture (from low level to higher level ).

Docs: Release Schedule: Missing description regarding edge

I couldn't find info regarding the edge channel which is possible to install via the GUI installer.

docs.ubports.com/about/process/release-schedule.rst

documentation structure proposal

hi,
found that daily use or advance use is not very accurate
my proposition for documentation structure:

• ABOUT

  • ...

• CONTRIBUTE

  • ...

• UBUNTU TOUCH INTERNALS

  • overview ( here we talk about OS architecture and Mobile specific things )

• HOWTOS

  • Install Ubuntu Touch ( Here maybe find all things related to how install on supported device, howto port to new devices )

  • Switch release channels

  • Shell access via adb

  • Shell access via ssh

  • Screen Casting your UT device to your computer

  • Reverse tethering

    • ...

• APP DEVELOPPEMENT

  • Overview (intro confinement, link to ubuntu touch internals, click, languages, content hub, notifications, ... )
  • Build & Deploy
    • Install ( raw style )
    • Clickable
    • Ubuntu SDK IDE
  • Webapps
    • ...
  • Native apps
    • ...
  • Desktop X apps (with libertine and non-official way)
  • External resources (tutorials, templates, blogs)
  • ...

broken link on Contribute page

https://docs.ubports.com/en/latest/contribute/index.html

It says "If you’re just getting started, we always need help with :ref:thorough bug reporting <contribute-bugreporting-index>_. If you are multilingual, translations are also a great place to start."

I'm not sure how to fix this myself. It seems that removing the underscore helps. However, I have to python -m sphinx . _build at least TWICE for any change in this file to take effect, so maybe something else is going wrong here.

Another amend to Shell access via ssh page

Where it says:

Now start the ssh server:

sudo android-gadget-service enable ssh

This didnt start the ssh server on the phone for me, I had to add

sudo service ssh start

as I was getting many connection refused errors on trying to connect from my machine.

These may be simple things but for beginners who are copying line by line I think it needs to be clear.

Broken links in API docs

I found:
in «See also Resolution Independence .»
https://api-docs.ubports.com/sdk/apps/qml/Ubuntu.Components/Units.html#detailed-description

a broken link to
https://api-docs.ubports.com/sdk/apps/qml/UbuntuUserInterfaceToolkit/resolution-independence/

Original link
https://docs.ubuntu.com/phone/en/apps/api-qml-development/UbuntuUserInterfaceToolkit.resolution-independence

Update Android apps Page

The page regarding the installation of Android apps breaks the Wifi functionality on the Nexus 5.

It really should be noted somewhere that unless you're on the development branch, not the stable branch, this will happen. Additional, when on the development branch, there is no need to flash the anbox-boot-hammerhead.img image via fastboot anymore. The only required steps are the second portion of installing it via apt as copied below.

adb shell # connect from your host computer to your UT device
sudo mount -o rw,remount /
sudo apt update
sudo apt install anbox-ubuntu-touch android-tools-adb
anbox-tool install
exit

See issue #1264 for reference.

Broken link

In docs.ubports.com/porting/building-ubports-boot.rst:

Now that you have ubports-boot built, you can move on to :doc:installing-16-04.

Should be something like:

Now that you have ubports-boot built, you can move on to :doc:installing-16-04 <userguide/install>.

Wrong sample code for Ubuntu.Components ViewItems under dragUpdated section

Description

In the first example, it uses the syntax ListViewDrag however it is incorrect.
The correct syntax is ListItemDrag.

https://api-docs.ubports.com/sdk/apps/qml/Ubuntu.Components/ListItem.html#sdk-ubuntu-components-listitem-dragmode

Link translations

The language switch is very well hidden. I guess no one has ever found it, yet. Maybe we could link existing translations from the start page so users have chance to become aware of them?

Broken link to Krillin ROM

The link to Krillin's ROM is broken, it's the only one that's broken.
https://docs.ubports.com/en/latest/userguide/install.html#install-on-legacy-android-devices

remove/change all unity8 references with lomiri or other string

all the documentation talk about unity8 instead of lomiri, also all the libraries with old ubuntuish name probably need to be updated to newer one.

so probably is needed a list of name changes like [oldname1]->[newname1], [oldname2]->[newname2]
also the changing procedure probably can be done instantaneously with appropriate sedcommand ...something like sed -i 's/[oldname]/[newname]/g' *

The section about App development - On device needs an overhaul

I find this section really hard to read
https://docs.ubports.com/en/latest/appdev/index.html#on-device-software-development

It reads like blog posts copied over. The text doesn't integrate into the website. It is an entanglement of some generic UT app dev aspects with two very specific IDEs without clear structure what goes where. Some places are walls of text. Some places look like malformed markups.