Jump to content




Photo
Posted by Josh Klint, 14 March 2017 · 0 views

I've been getting good results storing documentation data in XML files.  This allows me to make changes to the way documenation is displayed, without updating hundreds or thousands of pages.  I can also write documentation without as much HTML markup.  For example, bullets can automatically be inserted in line breaks for the syntax info.  Javascript-based search engines usually require all page contents to be store in an array, so this gives us an easy way to collect that data.

Since XML is a known standard, this makes it a bit easier to outsource the documentation content.

Here is a sample file I am working with.
<?xml version="1.0"?>
<page>
<title>SetPosition</title>
<description>Sets the position of an entity in 3-dimensional space, using local or global coordinates.</description>
<cppsyntax>
void Entity::SetPosition(const float x, const float y, const float z, const bool global = false)
void Entity::SetPosition(const Vec3& position, const bool global = false)
</cppsyntax>
<luasyntax>
nil Entity:SetPosition(number x number y, number z, bool global = false)
nil Entity:SetPosition(Vec3 position, bool global = false)
</luasyntax>
<parameters>
x: X component of the specified position.
y: Y component of the specified position.
z: Z component of the specified position.
position: the position to set.
global: indicates whether the position should be set in global or local space.
</parameters>
<remarks>
An entity can be positioned in local or global coordinates. Local coordinates are relative to the entity parent's space.

If the entity does not have a parent, local and global coordinates are the same.

&#60;img src='img/552px-Space.png' /&#62;

Leadwerks uses a left-handed coordinate system.  This means that if you hold your left hand as shown below, your middle finger, index finger, and thumb will point in the directions of the X, Y, and Z axes, respectively.
&#60;img src='img/image2.jpg' /&#62;
</remarks>
<luaexample>
--Create a window
window = Window:Create()
context = Context:Create(window)
world = World:Create()
local camera = Camera:Create()
camera:SetRotation(35,0,0)
camera:Move(0,0,-6)
local light = DirectionalLight:Create()
light:SetRotation(35,35,0)
--Create a model
model = Model:Box()
while true do
		if window:Closed() or window:KeyHit(Key.Escape) then return false end
		model:SetPosition(Math:Sin(Time:GetCurrent()/10.0),0,0)
		Time:Update()
		world:Update()
		world:Render()
		context:Sync()
end 
</luaexample>
<cppexample>
#include "Leadwerks.h"
using namespace Leadwerks;
int main(int argc, const char *argv[])
{
		Leadwerks::Window* window = Window::Create();
		Context* context = Context::Create(window);
		World* world = World::Create();
		Camera* camera = Camera::Create();
		camera->SetRotation(35, 0, 0);
		camera->Move(0, 0, -4);
		Light* light = DirectionalLight::Create();
		light->SetRotation(35, 35, 0);
		//Create a model
		Model* model = Model::Box();
		while (true)
		{
				if (window->Closed() || window->KeyDown(Key::Escape)) return false;
				model->SetPosition(Math::Sin(Time::GetCurrent() / 10.0), 0, 0);
				Leadwerks::Time::Update();
				world->Update();
				world->Render();
				context->SetBlendMode(Blend::Alpha);
				context->DrawText(model->GetPosition().ToString(), 2, 2);
				context->Sync();
		}
		return 0;
}
</cppexample>
</page>

Even the table of contents can be store in XML, which provides a listing of all pages and a way to automatically create the search index and a list of all topics:
<?xml version="1.0"?>
<contents>
	<topics>
		<topic>
			<title>Tutorials</title>
			<openstate>true</openstate>
			<topics>
				<topic>
					<title>1. Editor</title>
					<openstate>true</openstate>
					<topics>
						<topic><title>1.1 Editor Interface</title><openstate>true</openstate></topic>
						<topic><title>1.2 Scene Panel</title></topic>
						<topic><title>1.3 Textures</title></topic>
						<topic><title>1.4 Materials</title></topic>
						<topic><title>1.5 Models</title></topic>
						<topic><title>1.6 Terrain</title></topic>
					</topics>
				</topic>
				<topic>
					<title>2. Games</title>
					<topics>
						<topic><title>2.1 Marble Platformer</title></topic>
					</topics>
				</topic>
				<topic>
					<title>3. Lua Programming</title>
					<topics>
						<topic><title>3.1 Introduction to Lua</title></topic>
					</topics>
				</topic>
				<topic>
					<title>4. C++ Programming</title>
					<topics>
						<topic><title>4.1 Introduction to C++</title></topic>
					</topics>
				</topic>				
			</topics>				
		</topic>
		<topic>
			<title>Script Reference</title>
			<topics>
				<topic><title>AI</title></topic>
				<topic><title>Analytics</title></topic>			
			</topics>			
		</topic>
		<topic>
			<title>API Reference</title>
			<topics>
				<topic>
					<title>Object</title>
					<openstate>true</openstate>
					<topics>
						<topic><title>Asset</title></topic>
						<topic><title>Analytics</title></topic>
					</topics>
				</topic>			
			</topics>				
		</topic>		
	</topics>
</contents>




I am using a lot of PHP right now, which does not run on a client web browser, but I guess this format could be turned into anything including local HTML documentation or a PDF.
Will this page be available for XML at some point?

http://www.leadwerks.com/werkspace/page/documentation
There's a topic in the programming forum that has a link to a table of contents XML file.

March 2017

S M T W T F S
   1234
567891011
12131415161718
19202122232425
262728 29 3031 

Search My Blog

Recent Entries

Recent Comments