From eeb5b13797e19246b12e857e81f470dce8041b6a Mon Sep 17 00:00:00 2001 From: Rivka Ligier Date: Sat, 7 Dec 2019 05:18:17 -0500 Subject: [PATCH] docs: restructure software documentation (#816) also re-phrased some sentences and fixed minor grammar errors --- docs/documentation/index.html | 265 +++++++++++++++++++--------------- 1 file changed, 145 insertions(+), 120 deletions(-) diff --git a/docs/documentation/index.html b/docs/documentation/index.html index 23efbd82..1ad6d6a7 100644 --- a/docs/documentation/index.html +++ b/docs/documentation/index.html @@ -81,21 +81,17 @@
-

QUICK START GUIDE

-

This short introduction will briefly guide you through the project setup and the user interface of Sourcetrail. The bullet point lists will tell you what to do:

-
- Tasks: - -
+

Welcome

+

This document is the official documentation of Sourcetrail and explains everything you need to know about working with the software.

+

For questions you may have that are not answered by this document, please send us an e-mail at: support@sourcetrail.com.

+ +

Overview

+

Sourcetrail is an interactive source explorer that simplifies navigation in existing source code by indexing your code and gathering data about its structure. Sourcetrail then provides a simple interface consisting of three interactive views, each playing a key role in helping you obtain the information you need:

-

Short description

-

Sourcetrail is an interactive source explorer that simplifies navigation in existing source code. Sourcetrail's aim is to give answers to all your questions about your source code. Sourcetrail first indexes your code and gathers data about its structure and then provides you a simple interface consisting of three interactive views, each playing a key role in getting information:

- +
-

Sourcetrail currently supports the languages C/C++ and Java. Much of the UI design is therefore based on these languages and might change as soon as other languages are supported. For more information have a look at supported languages.

+ +

Note: Sourcetrail currently supports the languages C/C++ and Java. Much of the UI design is therefore based on these languages and might change as soon as other languages are supported. For more information have a look at supported languages.

-

Starting up Sourcetrail

-

Once you installed Sourcetrail successfully you are ready to run the application.

+

Supported Languages

+

C

+

C support is powered by Clang 8.0.1. For issues loading C code, please have a look at Clang language compatibility or report a bug in our bug tracker.

+ +

C++

+

C++ support is powered by Clang 8.0.1. For more Information please visit Clang C++ Status. For issues loading C++ code, please have a look at Clang language compatibility or report a bug in our bug tracker.

+ +

Java

+

Sourcetrail includes support for Java 10 and lower which is powered by Eclipse JDT. If you encounter any issues while using Sourcetrail on a Java project, please let us know by providing a minimal example in our bug tracker.

+ +

Python

+

Sourcetrail includes beta support for Python 2 and Python 3 which is powered by our open-source SourcetrailPythonIndexer. If you encounter any issues while using Sourcetrail on a Python project, please let us know by providing a minimal example in our bug tracker.

+ + +
+ +

Getting Started

+ +

This short introduction will briefly guide you through the project setup and the user interface of Sourcetrail. The bullet point lists will provide you with the next steps to take:

+ +

Starting Up Sourcetrail

+ +

Once you've downloaded Sourcetrail successfully you are ready to run the application. For assistance wth installation, visit the installation section.

+
Tasks: +
+ +

After launching Sourcetrail you will see the Start Window. From here you can create your own project or choose a pre-indexed one.

+ +
+ Tasks: +
-

Start Window

-

After launching Sourcetrail you will see the Start Window. Now you can create your own project or choose a pre-indexed one.

+ + +

Creating a New Project

+ +

When creating a new Sourcetrail project you will use the Project Setup Wizard . This wizard splits the setup process into several subsequent steps. Depending on your project's structure and the used build system, there are different types for project setup. Choosing the correct setup method is important and can make the setup process a lot easier.

+
Tasks:
- -

Creating a Project

-

When creating a new Sourcetrail project you will use the Project Setup Wizard. This wizard splits the setup process into several subsequent steps. Depending on your project's structure and the used build system there are different types for project setup. Choosing the right setup method is important and can make the setup process a lot easier.

- -

In the first step of the project setup you will just need to specify name and location of your Sourcetrail project.

-
-
+
+

Add Source Group

+ +

Sourcetrail projects consist of multiple Source Groups. Each Source Group uses a certain language, a set of files, and all configurations to index these files. There are different types of Source Groups for each supported programming language. In addition, creating a single Source Group is sufficient for most projects.

+ +

Scroll past the image for detailed instructions on setting this up.

+
Tasks:
-

Choosing the right project setup

- -

Sourcetrail projects consist of multiple Source Groups. Each Source Group uses a certain language, a set of files and all configurations to index these files. There are different types of Source Groups for each supported programming language. Creating a single Source Group is sufficient for most projects.

-
@@ -162,7 +190,8 @@
-

Source Group setup for C/C++

+

Source Group Setup for C/C++

+

The Source Group setup types for C & C++ are the same.

This video gives you a detailed look into project setup for C++, including best practices and strategies on how to fix errors:

@@ -198,9 +227,9 @@
- Create empty + Create Empty -

If none of the above options apply to your project, please continue at Create an empty C/C++ Source Group and come back here as soon as the project is created.

+

If neither of the above options apply to your project, please continue at create an empty C/C++ Source Group and return here once the project is created.

@@ -210,7 +239,7 @@
-

Source Group setup for Java

+

Source Group Setup for Java

Are you using Gradle? @@ -232,7 +261,7 @@
- Create empty + Create Empty

If you do not have your project configured using Gradle or Maven, please continue at Create an Empty Java Source Group and come back here as soon as the project is created.

@@ -242,7 +271,7 @@ -

Source Group setup for Python

+

Source Group Setup for Python

Create empty @@ -254,74 +283,83 @@ +

Source Indexing

+ +

After the project is created, Sourcetrail will ask you whether you want to start indexing. Click Start and wait for the indexing to complete. This may take a bit of time. The Indexing Dialog and the Status Bar will give you information about the progress. Otherwise the UI will be empty. Sourcetrail indexes all named symbols and their relationships throughout the provided source files.

+
Tasks:
-

Source Indexing

-

After the project is created, Sourcetrail will ask you whether you want to start indexing. Click Start and wait for the indexing to finish, which might take a little while. The Indexing Dialog and the Status Bar will give you information about the progress. Otherwise the UI will be empty. Sourcetrail indexes all named symbols and their relationships throughout the provided source files.

+ +

After indexing is completed, Sourcetrail will show an overview of all indexed symbols in the graph view and some statistics in the code view.

+ +

Troubleshooting Errors

+ +

If the indexing yields errors, the status view will be shown with a list of errors. You can click on the errors label on the right side of the status bar or on one of the errors in the table to see their location.

+
Tasks:
-

After indexing has finished, Sourcetrail will show an overview of all indexed symbols in the graph view and some statistics in the code view.

-

If the indexing yields errors, the status view will be shown with a list of errors. You can click on the errors label on the right side of the status bar or on one of the errors in the table to see their location.

-
- Tasks: - -
+

User Interface

+ +

As mentioned earlier, Sourcetrail's user interface is split into three main views. Their arrangement can be adjusted as preferred and can also be detached from the main window and split into different screens (see Window Widgets).

+ +

All three views display information about the currently selected symbol:

-

UI Intro

-

As already mentioned Sourcetrail's user interface is split into three main views. Their arrangement can be changed however you wish, you can even detach them from the main window and put them on different screens (see Window Widgets).

-

The three views show information about the currently selected symbol. The search field provides the name, the graph visualization shows its relationships to other symbols and the code view displays all locations the symbol gets referenced throughout the codebase.

-

Search Field

-

The search field allows for easy access to all indexed symbols. Use it to find all the classes and functions you wish to investigate. Apart from that is also holds the UI buttons for navigating back & forward as well as refreshing.

+

1. Search Field

+

The Search Field allows for easy access to all indexed symbols. Use it to find all classes and functions you wish to investigate. In addition, it also holds the UI buttons for navigating back & forward as well as refreshing.

+
-

When entering a search query the autocompletion popup will provide you with a concise list of all matching symbols. Note that Sourcetrail uses a fuzzy matching algorithm, that allows you to skip characters while entering a query.

+ +

When entering a search query, the autocompletion popup will provide you with a concise list of all matching symbols. Note that Sourcetrail uses a fuzzy matching algorithm, that allows you to skip characters while entering a query.

+
-

Graph Visualization

-

The graph visualization displays the currently selected symbol in an active state and all other symbols it shares relationships with. The visualization is made up of nodes and edges.

+

2. Graph Visualization

+ +

The graph visualization displays the currently selected symbol in an active state and all the other symbols it shares a relationship with. The visualization is made up of nodes and edges.

+ +
@@ -352,7 +390,8 @@

Legend:

For a full list on all existing nodes and edges take a look at the integrated Graph Legend by clicking the ?-button in the bottom right corner of the Graph View. -

Code View

+

3. Code View

+

The code view displays all locations of the currently active symbol within the indexed source files. It does not allow for editing the source code. Syntax highlighting is used to increase readability. Source locations that are surrounded by a box when hovered can be clicked to activate the respective symbol. Active source locations are highlighted.

@@ -388,72 +427,28 @@
-

For more information please have a look at Code View Files.

+

For more information, please visit the Code View Files section.

-

Start exploring!

-

After reading this quick guide, you know the basics of Sourcetrail's user interface and you are able to start exploring your codebase. Sourcetrail will allow you to see your source code from a whole new perspective, by giving you a concise overview of its parts and a faster way of drilling down to its internals, while always maintaining the connection to the implementation details of the actual source code.

-

For more detailed information please have a look at the much more extensive instruction manual below.

-

If you have feedback for us, please don't hesitate and let us know by writing to support@sourcetrail.com, we'd be glad to hear from you.

+

Start Exploring!

+

At this point, you should have an understanding of the basics of Sourcetrail's user interface and can begin exploring your codebase. Sourcetrail will allow you to see your source code from a whole new perspective, by giving you a concise overview of its parts and a faster way of drilling down to its internals, while always maintaining the connection to the implementation details of the actual source code.

+ +

Please take look at the much more extensive instruction manual below for detailed information.

+

If you would like to provide feedback, please do not hesitate to reach out to us via email: support@sourcetrail.com, we'd love to hear from you!

+

The Sourcetrail team wishes you a good start with our product, lots of saved time, increased productivity and much cleaner code.

+
Tasks:
    -
  • Start exploring & have fun!
    • +
  • Start exploring and have fun!
-

INTRODUCTION

- -

About this document

-

This document is the official documentation of Sourcetrail and explains everything you need to know about working with it.

-

If you have questions not answered by this document, please write us an e-mail to support@sourcetrail.com.

- - -

Supported Languages

-

C

-

C support is powered by Clang 8.0.1. If you have a problem loading C code, please have a look at Clang language compatibility or report a bug at our bug tracker.

- -

C++

-

C++ support is powered by Clang 8.0.1. For more Information please visit Clang C++ Status. If you have a problem loading C++ code, please have a look at Clang language compatibility or report a bug at our bug tracker.

- -

Java

-

Sourcetrail includes support for Java 10 and lower which is powered by Eclipse JDT. If you encounter any issues while using Sourcetrail on a Java project, please let us know by providing a minimal example at our bug tracker.

- -

Python

-

Sourcetrail includes beta support for Python 2 and Python 3 which is powered by our open-source SourcetrailPythonIndexer. If you encounter any issues while using Sourcetrail on a Python project, please let us know by providing a minimal example at our bug tracker.

- -

FAQ

- -
-
-

Can I use Sourcetrail on confidental source code?

-
-
- Yes. Sourcetrail works completely offline and establishes no connection to the internet whatsoever. All data stays on your computer. -
-
- -
-
-

What happens to the indexed data?

-
-
-

Sourcetrail does two things with the data collected during indexing:

-
    -
  1. The data is stored in the .srctrldb file in the same directory as the .srctrlprj file. This database file is used by Sourcetrail to serve its purpose of letting you navigate your source code. And it allows Sourcetrail to reopen the project without reindexing the source code every time.
    2. -
  2. If logging is enabled, some of the data gets logged into a log file saved in data/logs. These logs can be useful to us for fixing bugs. We might ask for log information on bug reports, but you should only provide it, if your source code is not confidental.
    3. -
-
-
- - -
- -

INSTALLATION

+

Installation

On Windows

Download and open the zip file and extract its contents into a temporary folder of your choice. Run the setup.exe and go through the wizard. You can now launch Sourcetrail from your start menu.

@@ -532,7 +527,7 @@
-

USER INTERFACE

+

Interface

Main Window

@@ -1890,7 +1885,7 @@
-

PROJECT SETUP

+

Project Setup

Project Setup in Sourcetrail is done via the Project Setup Wizard, which can be accessed on the Start Window by clicking New Project or from the Project Menu with the New Project action.

The Project Setup Wizard lets you create a new Sourcetrail project. It allows for defining name and location of your Sourcetrail project and adding several Source Groups, that define which source files will be indexed. There are several ways to create Source Groups. It is sufficient to add only one Source Group for most projects.

@@ -2667,7 +2662,7 @@
-

COMMANDLINE

+

Command Line

Currently you can use the command line to configue Sourcetrail or index a Sourcetrail project.

@@ -2733,7 +2728,7 @@
-

CODE EDITOR PLUGINS

+

Code Editor Plugins

In order to make Sourcetrail the perfect partner for your development workflow you can connect Sourcetrail with different code editors. You can find more information on the plugins in Sourcetrail's download package located in the folder /ide_plugins. Have a look at the following list of supported code editors to find out what editors are currently supported.

We are eager to expand the range of supported editors, so if you can't find a plugin for the code editor you are using, please let us know by writing to support@sourcetrail.com.

The plugins are Opensource and available on github.

@@ -3139,6 +3134,36 @@
+ +

Frequently Asked Questions

+ +
+
+

Can I use Sourcetrail on confidental source code?

+
+
+ Yes. Sourcetrail keeps the data completely offline and unless disabled, will only establish a connection to the internet to check if a more recent version is available. +
+
+ +
+
+

What happens to the indexed data?

+
+
+

Sourcetrail does two things with the data collected during indexing:

+
    +
  1. The data is stored in the .srctrldb file which is in the same directory as the .srctrlprj file. This database file is used by Sourcetrail to serve its purpose of letting you navigate your source code and also allowing Sourcetrail to re-open the project without re-indexing the source code each time. +

    Note: The .srctrldb file is actualy a .sqlite database file and can be inspected using the DB Browser for SQLite.

    +
    2. + +
  2. If logging is enabled, some of the data gets logged into a log file saved in data/logs. These logs can be useful to us for fixing bugs. We may ask for log information on bug reports, but you should only provide it, if your source code is not confidental.
    3. +
+
+
+ +
+
Coati Software OG
Jakob-Haringer-Straße 1/127