Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
titleAdvanced Features

For more complex documentation scenarios, projectdoc provides a number of advanced features.

Section
titleInherit Properties from Spaces

projectdoc allows you to set spaces in hierarchies using the delegate-space Delegate Space property, which is a space property. Any properties defined in delegate spaces are automatically visible in the delegating space.

Please refer to Space Hierarchies for more information on this topic.

Section
titleOrganize Properties by Extension Documents

The number of space properties may be rising with time. To manage large amounts of space properties you may group them semantically and store them on separate pages.

Use the space property space-properties-extension Space Properties Extension (Space Property) to list pages that provide additional space properties as a space property on your space home page.

Section
titleUser-specific Settings

Properties specified within the properties table of the Document Properties Marker Macro on the home page of the user are also taken into account when rendering space properties.

These properties are used to define user-specific home pages for document types or allow users to switch roles.

Tip Box

Using user space properties may cause confusion within a team. One team member may have set a property another team member has not and therefore they get different renderings of a page. The reason for the difference is often not instantly obvious. Compare the properties for each user with the Display All Space Properties to see the differences in the configuration. The macro also shows where a particular space property is defined.

Use Space Property Controls to limit the export of space properties.

Section
titleTemplating with Space Properties

Template authors may want to display certain content only if a given space property is set. The Content Marker Macro allows to specify space properties that need to be set to show the content. 

This option is also available for sections.

Section
titleUse Cases

Here are a couple of use cases that employ space properties.

Section
titleMaven Projects

With projectdoc you may create spaces for software projects built with Maven. Create a space by reading the project's POM file. The properties of the POM are automatically made available as space properties.

Depending on the version of the product, different space properties may be enforced by using space properties extensions.

Note Box

The doctype add-on is not yet available on the Atlassian Marketplace. Large POM files take a long time to create the space. While developers may deal with this, other users may be annoyed by the import process.

Until this problem is fixed users may choose to fork and build the add-on on their own. It is available on Bitbucket!

For more information on documenting projects built with Maven, please refer to:

Tour
render-as-definition-listtrue
Section
titleBeing a Pretender

Sometimes an author needs to look at a page as if she is a reader. For these use cases there is the pretend-being-a Pretend Being A property that is only allowed to be specified as a user space property.

Section
titleUser-specific Home Pages

Users may want to define home pages for certain types of documents individually. It is also possible to store documents of a given subject automatically to a specific page.

The example shows how to set the home page for all Resource documents to 'Library' and direct all documents with the Subject 'Team Announcement' to the 'Announcements' page.

For more information on this topic, please refer to:

Tour
render-as-definition-listtrue
Section
titleMacro Configuration

A number of macros in the PDAC1 refer to space properties for a central configuration.

Here are two examples:

Section
titleRemote Information Systems

Space properties allow to specify URLs to remote information systems to be used by macros of the Information Systems Extension. If the URL to such an information system changes, the URL needs to be edited only in one place.

Display Table
doctypemacro
selectName, Iteration, Short Description
where$<Extension>=[Information Systems Extension]
header-translationsIteration=Status
render-counter-columntrue

Note Box

Prior to version 1.11 of the projectdoc Toolbox these macros where part of the add-on. We decided to move them to an extension add-on since they are not required by all users. The extension is available for free, but needs the commercial projectdoc Toolbox Add-on installed.

Section
titleRendering Configuration

The Code Block Placeholder Macro takes advantage of space properties. You may for example define a default language with the code-language Code Language property.

Section
titlePrerequisites

...

Section
titleResources
Section
titleSpace Resources

Find more information on using spaces with projectdoc here:

Display Table
selectName, Short Description, Doctype
where$<Tags> = [Space]
header-translationsDoctype=Type

Section
titleGet Started

To get started with the projectdoc Toolbox have a look at the following resources:

Tour
replace-title-with-nametrue
TitleShort Description
Introduction for projectdoc new Users 
Hands-on Tutorial 
Basic Concepts and Conventions for projectdoc 
projectdoc on the Atlassian MarketplaceInstall the projectdoc Toolbox and doctype add-ons via the Atlassian Marketplace.

...