Note: You can freeze your build configuration settings into an Ant script (e.g., build.xml).
The documentation for the 3rdParty SDK was all in one long web page, and it had reached the point where had become unwieldy; the content wasn’t easy to discover. I needed to break it up into several topics, and arrange them in a logical hierarchy. I was currently working in Dreamweaver, and was considering creating a new document based on a template with a TOC on the left. I remembered that I once created a prototype web site that was like that, and I hunted through my hard drive, looking for it, with the intention of copying the look and feel. I ended up stumbling on another doc set that fit the bill, that I created using oXygen XML Editor. I had forgotten about using oXygenXML Editor, and it hadn’t occurred to me that this would actually be a really good approach to use for the 3rdParty SDK docs.
Here what I did to transform the content into a DITA project.
The first thing to remember is you’re actually authoring this content in 3rdParty repo (android_mobile_verification). You’re authoring it in the doc repo. And this (content authoring) will be unusual for that repo.
I think you’ll have to experiment, because this is getting too complicated to be able to predict what you need to do.
Note: Open the oXygen XML perspective to ensure that you get all of the available DITA Map Transforms. Otherwise you won’t see all of the tools, windows, transforms, that come with the oXygen XML Editor Eclipse plugin.
In the MobileVerification project (the android_mobile_verification repo, feature/api_doc), add a new folder called “docs”.
With the project folder selected, click File > New, and select oXygen XML Editor > New from Templates. Click Next.
Select Framework templates > DITA Map > map > Map. Click Next.
Set a value for the parent folder: MobileVerification/docs
Click Finish.
I think your doc set falls into the software documentation domain. See: 3.2 Technical Content Elements (http://docs.oasis-open.org/dita/v1.2/os/spec/langRef-technicalContent.html).
With the project folder selected, click File > New, and select oXygen XML Editor > New from Templates. Click Next.
Select Framework templates > DITA > topic > Concept. Click Next.
Set a value for the parent folder: MobileVerification/docs
Click Finish.
For more information on this procedure, see: http://www.oxygenxml.com/doc/ug-editorEclipse/#topics/webhelp-customization-add-image-to-title.html
Copy the file:
C:\Users\Chris\src\python_rest_api\doc\user\v1\source_statictelesign-logo.png
to
C:\opt\eclipse\plugins\com.oxygenxml.editor_16.1.0.\v2014102117\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\oxygen-webhelp\resourcesimg
I’ll use my path statement to demonstrate a path statement for a typical Eclipse installation.
%SystemRoot%;%SystemRoot%\system32;%SystemRoot%\System32\Wbem;%SYSTEMROOT%\System32\WindowsPowerShell\v1.0;C:\Androidsdk\platform-tools;%JDK_HOME%\bin;%JAVA_HOME%\bin;%PYTHON_HOME%;%PYTHON_HOME%\Scripts;C:\Program Files (x86)\Gitcmd;C:\Program Files (x86)\Gitbin;%MinGW_HOME%/bin;%MERGEHOME%\%ANT_HOME%\bin;X:\JGSoft\Tools\HTML Tidy and XML Tidy;C:\Program Files\InteliCLS\Client;C:\Program Files (x86)\InteliCLS\Client;C:\Program Files\Intel\Intel(R) Management Engine Components/DAL;C:\Program Files\Intel\Intel(R) Management Engine Components\IPT;C:\Program Files (x86)\Intel\Intel(R) Management Engine Components\DAL;C:\Program Files (x86)\Intel\Intel(R) Management Engine Components\IPT;C:\Program Files (x86)\Windows Kits\8.0\Windows Performance Toolkit;C:\Program Files\Microsoft SQL Server\100\Tools\Binn;C:\Program Files\Microsoft SQL Server\100\DTS\Binn;C:\Program Files (x86)\Microsoft SQL Server\100\Tools\Binn;C:\Program Files (x86)\ATI Technologies\ATI.ACECore-Static;%OXYGEN_HOME%;X:\FCIV;C:\Program Files (x86)\QuickTime\QTSystem;C:\Perl64bin;C:\Perl64\site\bin
Eclipse uses path variables in build configuration scripts to create portable projects.
Environment variables are defined within a hierarchy, which defines each one’s scope of access.
The operating system. These are the current user’s environment variables (UserDomain.UserName). For Example,
USERNAME = Chris
The Eclipse IDE and the Java Virtual Machine ( referred to as System Properties of the Java Platform). To maximize portability, never refer to an environment variable when the same value is available in a System Property. For example, if the operating system provides a user name, it will always be available in the system property user.name.
The current Workspace in Eclipse.
The current Project within the current workspace. These are the environment variables that the build configuration can access directly. For example,
Path: /java_3rdParty
Use PROJECT_LOC as a starting point, and create
JAVADOC_LOC = ${PROJECT_LOC}\doc LIBRARIES_LOC = ${PROJECT_LOC}\libs SOURCE_LOC = ${PROJECT_LOC}\src
Note: To use these in an Ant script, you have to define and assign equivalent local variables.
Eclipse adds /bin folder for compiled Java class files.
Under the Source menu.
Collapse Code: Ctrl + - Uncollapse Code: Ctrl + = Collapse Code (All): Ctrl + 9 Uncollapse Code (All): Ctrl + 0
Ctrl + Shift + Right Click
Only available in the Java Editor.
Ctrl + Shift + B
Imagine if the Project Explorer contained a filtered view of resources in your project. I.e., a subset of it. E.g., a view that ignores the Test directory, and everything in it; but includes parts of another project within the workspace. If you could save such a view, it would essentially be a Working Set.
These are just like Environment Variables, but they apply to Eclipse, the Current Workspace, and the Current Project. Here are some examples.
ECLIPSE_HOME: C:\Program Files\eclipse\ WORKSPACE_LOC: A:\Documents\Eclipse\Projects\Practice PROJECT_LOC: A:\Documents\Eclipse\Projects\Practice\TestSphinxWiz
Your workspace is a folder that contains a subfolder called “.metadata”.
Counter to what you might expect, the workspace folder doesn’t physically contain project folders. It contains them by reference.
If you’re used to using Visual Studio and Source Depot, then you’re in for a bit of a paradigm shift when you use Eclipse and git.
Note: The location of your Eclipse Workspace, and the location of your source code are mutually exclusive. I.e., you might think that the workspace should encompass your local git repo – but it doesn’t, and actually can’t. For example, I have all of my local repos on the C: drive (in C:\Users\Chris\src\), yet I have my default Workspace on my A: drive (in A:\Documents\Eclipse\Projects\).
Think of it like this: when a multi-media app manages your music collection, it doesn’t move all of your media files into it’s program directory. Instead, it builds a database the contains records for corresponding media files. Each record contains a pointer to the media file, along with all of the details contained in its ID3 tag.
You’re doing something similar when you build an Eclipse Workspace. In the case of Eclipse though, the database is stored in a “Workspace;” a folder on your file system that contains a folder called “.metadata”.
Window > Preferences > Teams > Git
Default Repository Folder (Git_HOME):
${env_var:GITSOURCE}/
Eclipse reads these details straight from your user configuration file (%USERPROFILE%.gitconfig).
The only thing I had customized in this file was my merge tool: “C:\Program Files (x86)\Beyond Compare 4\BCompare.exe”
To work on Git-hosted projects in Eclipse, you must import them into Eclipse using the Git Project Import Wizard. You can use Import Existing Project.
The procedure differs between projects hosted publicly on GitHub, and projects hosted on 3rdParty’s private repo server.
Here’s how to get a local enlistment to the privately hosted 3rdParty REST API Git repository. Before you begin, establish a VPN connection to 3rdParty.
git@git.c11.3rdParty.com:python_rest_api.git
You’re prompted to input your password.
To work on a project hosted on GitHub:
The Updater service in Eclipse is based on Equinox p2, the Equinox framework OSGi implementation.
The OSGi (Open Service Gateway initiative) specification describes a modular system and a service platform for the Java programming language that implements a complete and dynamic component model, something that does not exist in standalone Java/VM environments.
When you run Help > Check for Updates, the Updater checks for system and component (addin) updates according to a list of “Available Software Sites” – which are p2 repositories. p2 stand for “Provisioning”.
Preferences > Install/Update > Available Software Sites
In my experience, this mechanism is buggy. You have to manually tweak the list (by adding, deleting, and editing) the items in the list.
http://wiki.eclipse.org/Eclipse_Project_Update_Sites
Here’s a list of URLs that you can visit to find the latest Update URI for a particular component.
<?xml version=”1.0″ encoding=”UTF-8″?>
<bookmarks>
<site url=” https://dl-ssl.google.com/android/eclipse/” selected=”true” name=”ADT Plugin”/>
<site url=” http://download.eclipse.org/webtools/updates” selected=”true” name=”Eclipse Web Tools Platform Repository”/>
<site url=” https://sourceforge.net/projects/eclipsejsonedit/files/update” selected=”true” name=”eclipse-json-editor”/>
<site url=” http://e-p-i-c.sf.net/updates/” selected=”true” name=”EPIC – Perl Editor and IDE for Eclipse”/>
<site url=” http://nextinterfaces.com/http4e/install/” selected=”true” name=”HTTP4e”/>
<site url=” http://download.eclipse.org/mylyn/releases/luna” selected=”true” name=”Mylyn for Eclipse Luna”/>
<site url=” http://www.oxygenxml.com/InstData/Editor/Eclipse/site.xml” selected=”true” name=”oXygen XML Editor Install”/>
<site url=” http://pydev.org/updates/” selected=”true” name=”PyDev Update Site”/>
<site url=” http://resteditor.sourceforge.net/eclipse/” selected=”true” name=”ReST Editor Update Site”/>
<site url=” http://download.eclipse.org/releases/luna/” selected=”true” name=”The Eclipse 4.4 (Luna) Updates”/>
<site url=” http://download.eclipse.org/webtools/repository/luna” selected=”true” name=”The Eclipse Web Tools Platform (WTP) software repository”/>
<site url=”http://www.oxygenxml.com/InstData/Editor/Eclipse” selected=”true” name=”update site: http://www.oxygenxml.com/InstData/Editor/Eclipse“/>
</bookmarks>
You can enhance Eclipse’s standard functionality by adding addins.
Help > Install New Software…
Work with: –All Available Sites–
Peruse the list that appears – and pick out the plugins that you want.
The oXygen XML Editor for Eclipse plugin adds so many useful features to Eclipse, that I bought a license for myself. It gives you a ton of editors (e.g., HTML), and each one runs against the associated DTD or schema to ensure that your code is well formed.
Get the latest version of the oXygen XML Editor for Eclipse by visiting: Download oXygen XML Editor.
The download landing page is a bit confusing. Scroll up to the top of the page and simply click the Download button.
Another web page appears, prompting you to fill in a form. Ignore it – the download begins automatically.
Click Save instead of Open – in case there’s a problem with the download.
The download takes about ten minutes.
After downloading the corresponding archive, use 7-Zip to extract its content into the “dropins” subfolder of the Eclipse folder.
Restart Eclipse.
Eclipse discovers the new addin and configures it for you.
Help > Install New Software…
Add the oXygen XML Editor software update endpoint URI: http://www.oxygenxml.com/InstData/Editor/Eclipse/site.xml
Paste this URI into the Work with field, and then click Add. The main window shows the work “Updating…”. When it is done, the list of updates, per Eclipse version displays. Check the box beside the latest version, and then click Next. The updates download and install, and then you must restart Eclipse for the changes to take effect.
After you install PyDev, you’ll be asked to reboot Eclipse.
Open the PyDev perspective to make sure that it installed properly.
When you reboot Eclipse, Eclipse might discover that PyDev has an incomplete configuration. If it does, then it presents you with choices for configuring it (Auto, Manual, Quick Auto, etc.). Choose Quick Auto.
You need this so you can run Sphinx and rebuild the docs for the 3rdParty REST API docs. You need the ReST Editor to configure a build configuration that will run make.bat.
The ReST Editor is an Eclipse plugin, and it adds a pretty reStructuredText editor to the Eclipse IDE. This is useful for authoring documentation for Python projects, where you use the Sphinx doc builder to automatically generate help builds.
Install it from the Eclipse MarketPlace.
The ReST Editor project is an open source project, and the code is hosted on the project site.
Note: The ADT plugin for Eclipse in no longer the official IDE for Android development; it’s now Android Studio, so you should install it at some point.
Follow the procedure on the “Installing the Eclipse Plugin” web site: http://developer.android.com/sdk/installing/installing-adt.html
Target Location for the Android SDK:
%POSIX_HOME%\android-sdks
http://resteditor.sourceforge.net/eclipse.Modelling > Sphinx SDK (Incubation) Modelling > UML2 Extender SDK Programming Languages > Javascript Development Tools Programming Languages > PHP Development Tools (PDT)
The first time you run Eclipse, you’re presented with a dialog that allows you to select a Workspace.
Accept the default location for your Workspace.
%USERPROFILE%\workspace
Check “Use this as the default and don not ask again”.
Note: If you’re reinstalling Eclipse, you mustn’t reuse the same default location for your workspace – this will corrupt your Eclipse installation. I learned this the hard way because I’d been using C:\Users\Chris\workspace, and I wanted to use that directory again; so I made a copy of it and saved it (into E:\Safe\workspace), and then cleaned C:\Users\Chris\workspace.
Before you start installing addins to Eclipse, make sure you’re working with the latest version (build) of Eclipse.
To update Eclipse, click Help > Check for Updates
Check the Status Bar for the update task’s progress.
In Eclipse, click Window > Preferences, and then systematically go through the items in the hierarchical menu in the left pane – and check each item’s configuration.
General
Appearance
Enable: Enable Animations
Compare/Patch/ > Text Compare
Enable: Initially show ancestry pane
Error Reporting
Enter your name and e-mail address
Workspace
Enable: Save automatically before build
Enable: Show workspace path in window title
Text file encoding: Other > UTF-8
Ant
Editor
Enable: Mark occurrences of the selected element in the current buildfile
Install/Update
Automatic Updates
Enable: Configure Eclipse so it automatically updates each time you start it.
Java
Editor
Folding
Enable: Comments, Inner types, and Members
Hovers
Enable: Combined Hover
Typing
Enable: Automatically insert at correct position > Semicolons > Braces
Team
Enable: Show the file author in compare editors
Git
History
Enable: E-mail addresses in Author/Committer columns
If the update process fails, throwing errors like this:
No repository found containing: osgi.bundle,org.eclipse.aether.api,1.0.1.v20141111
No repository found containing: osgi.bundle,org.eclipse.aether.connector.basic,1.0.1.v20141111
No repository found containing: osgi.bundle,org.eclipse.aether.impl,1.0.1.v20141111
Then you need to refresh the list of “Available Software Sites.”
To do so, select them all in Preferences > Install/Update > Available Software Sites, and then click Remove.
Any easy way to add them back is to Import the file named bookmarks.xml with the following content:
<?xml version=”1.0” encoding=”UTF-8”?> <bookmarks> <site url=”https://dl-ssl.google.com/android/eclipse/” selected=”true” name=”Android Developer Tools (ADT)”/> <site url=”http://download.eclipse.org/recommenders/updates/stable/” selected=”true” name=”Code Recommenders Stable Update Site”/> <site url=”http://download.eclipse.org/releases/luna/” selected=”true” name=”Eclipse Luna”/> <site url=”http://www.oxygenxml.com/InstData/Editor/Eclipse/site.xml” selected=”true” name=”oXygen”/> <site url=”http://pydev.sf.net/updates/” selected=”true” name=”PyDev Update Site”/> <site url=”http://resteditor.sourceforge.net/eclipse/” selected=”true” name=”ReST Editor Update Site”/> <site url=”http://jautodoc.sourceforge.net/update/” selected=”true” name=”update site: http://jautodoc.sourceforge.net/update/”/> </bookmarks>
When I was experimenting with Java projects, I continually ran into instances where projects depended on external libraries (JSON, IO, etc.). After downloading a few of them, I simply downloaded several of them – so I’d always have then on hand.
To add the common libraries, visit:
Get the latest version of Eclipse by visiting: Eclipse Downloads.
From the Eclipse Downloads landing page, click Eclipse IDE for Java Developers > Windows 64 Bit.
When the Run/Save toast appears, click Save.
When you click Run, the Eclipse Installer by Oomph runs.
Accept the installer default installation directory:
C:\java-neon
Set the option “Run this program as an administrator” on the Eclipse executable (i.e., on the file “C:\opt\eclipse\eclipse.exe”).
Pin the executable to the Taskbar. You can do this by Ctrl + clicking & dragging from File Explorer to the Taskbar.
You’re done. Go ahead and launch Eclipse.