RFC: (Preliminary) API Documentation Now Online

A place to discuss everything related to Newton Dynamics.

Moderators: Sascha Willems, walaber

RFC: (Preliminary) API Documentation Now Online

Postby oliver » Sat Sep 17, 2016 11:14 am

Hi,

I recently discovered the Newton Dynamics Engine. I was so impressed that I
created an account. This is my first post!

My main challenge has been the terse documentation. I know this has been
discussed before, and I will not warm it up again. Instead, I went ahead and
created an API documentation. Here it is:

http://newton-dynamics.readthedocs.io/en/apidoc/index.html

Under the hood it uses Doxygen/Sphinx based on Newton.cpp (with massive
refactorings in the doc-strings to make it Doxygen compatible).

The ReadTheDocs hosting is handy since it rebuilds the documentation whenever
someone pushes to the repo. It also free :)

The documentation contains simple installation instructions (Linux only) and
some very basic tutorials. These are a work in progress since they document
my journey as a Newton newcomer.

I would appreciate any (constructive) feedback on this endeavour, and whether
people think this is worth keeping.

Btw: the idea is not to replace the Wiki, but to ship a minimal set of "Getting
Started" instructions with the code base. Ideally, a CI system would ensure it
stays in sync... but I am getting ahead of myself :)
oliver
 
Posts: 36
Joined: Sat Sep 17, 2016 10:31 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby godlike » Fri Sep 23, 2016 10:16 am

That is some nice work! I would like to see that landing in Newton. Julio any thoughts?
User avatar
godlike
 
Posts: 58
Joined: Sun Mar 16, 2014 3:48 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby Julio Jerez » Fri Sep 23, 2016 1:23 pm

I received a PM from Oliver,
yes this weekend I will add what he has done to the archive.

Thanks Oliver for starting this project.
Julio Jerez
Moderator
Moderator
 
Posts: 12249
Joined: Sun Sep 14, 2003 2:18 pm
Location: Los Angeles

Re: RFC: (Preliminary) API Documentation Now Online

Postby oliver » Sat Sep 24, 2016 12:00 am

I am happy to help.

The pull request for the Doxygen file and updated
Newton.cpp is at https://github.com/MADEAPPS/newton-dynamics/pull/45

This PR does not include the Sphinx documentation I linked to in my earlier
post because I am unsure if people want it. I can easily add it, though.
oliver
 
Posts: 36
Joined: Sat Sep 17, 2016 10:31 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby oliver » Tue Sep 27, 2016 10:37 pm

I cannot help but notice that my PR for the docu has been tacitly ignored,
whereas other technical improvements found their way into Newton in the meantime.

Is something wrong with the PR? Is docu a non-issue for Newton users? Are the
maintainers simply too busy (I am happy to look after the docu related PRs if
that would help)?
oliver
 
Posts: 36
Joined: Sat Sep 17, 2016 10:31 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby Julio Jerez » Wed Sep 28, 2016 11:04 am

I merged all the request now.
sorry for the delay.
Julio Jerez
Moderator
Moderator
 
Posts: 12249
Joined: Sun Sep 14, 2003 2:18 pm
Location: Los Angeles

Re: RFC: (Preliminary) API Documentation Now Online

Postby Julio Jerez » Wed Sep 28, 2016 3:54 pm

ok I remove all instances to intrinsic _mm_castsi128_pd
it should build now with any older sse2 capable CPU

the function using that intrinsic was this,
Code: Select all
   DG_INLINE dgVector TestZero() const
   {
//      return dgVector (_mm_castsi128_pd(_mm_cmpeq_epi64 (m_typeIntLow, m_zero.m_typeIntLow)), _mm_castsi128_pd(_mm_cmpeq_epi64 (m_typeIntHigh, m_zero.m_typeIntHigh)));
      return dgVector (_mm_cmpeq_epi64 (m_typeIntLow, m_zero.m_typeIntLow), _mm_cmpeq_epi64 (m_typeIntHigh, m_zero.m_typeIntHigh)) & m_negOne;
   }


and it reduce to: using _mm_castsi128_pd
Code: Select all
pcmpeqq     xmm0,xmm2 
006F5DC6  movdqa      xmm2,xmmword ptr [dgVector::m_zero+10h (874260h)] 
006F5DCE  movapd      xmmword ptr [esp+23Ch],xmm1 
006F5DD7  pcmpeqq     xmm1,xmm2 
006F5DDC  movmskpd    eax,xmm1 
006F5DE0  add         eax,eax 
006F5DE2  add         eax,eax 
006F5DE4  movmskpd    ecx,xmm0 
006F5DE8  or          eax,ecx 


using and, and a contructor
Code: Select all
006F5DF2  pcmpeqq     xmm0,xmm2 
006F5DF7  movdqa      xmm2,xmmword ptr [dgVector::m_zero+10h (874260h)] 
006F5DFF  andpd       xmm0,xmmword ptr [dgVector::m_negOne (874310h)] 
006F5E07  movapd      xmmword ptr [esp+240h],xmm1 
006F5E10  pcmpeqq     xmm1,xmm2 
006F5E15  andpd       xmm1,xmmword ptr [dgVector::m_negOne+10h (874320h)] 
006F5E1D  movmskpd    eax,xmm1 
006F5E21  add         eax,eax 
006F5E23  add         eax,eax 
006F5E25  movmskpd    ecx,xmm0 
006F5E29  or          eax,ecx 


not a big deal since it is not use much, the benefit of using _mm_castsi128_pd Is that is reduces register pressure and does not read from memory.
I could make it conditional but is not worth the effort
Julio Jerez
Moderator
Moderator
 
Posts: 12249
Joined: Sun Sep 14, 2003 2:18 pm
Location: Los Angeles

Re: RFC: (Preliminary) API Documentation Now Online

Postby oliver » Thu Sep 29, 2016 7:21 am

Sounds all good to me :)

Do you also want the files that trigger the docu build on push? If so, should I include the "Starter Kit" section (I will probably add a few more sections as I go along).
oliver
 
Posts: 36
Joined: Sat Sep 17, 2016 10:31 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby Julio Jerez » Thu Sep 29, 2016 11:53 am

oliver wrote:Do you also want the files that trigger the docu build on push? If so, should I include the "Starter Kit" section (I will probably add a few more sections as I go along).

yes les us do that
Julio Jerez
Moderator
Moderator
 
Posts: 12249
Joined: Sun Sep 14, 2003 2:18 pm
Location: Los Angeles

Re: RFC: (Preliminary) API Documentation Now Online

Postby oliver » Fri Sep 30, 2016 6:24 am

Cool! PR is on github.

I started to cleanup the doc strings but, boy, Newton.cpp is humongous... :)
Most of the "World" related functions should be up to date now, however.
oliver
 
Posts: 36
Joined: Sat Sep 17, 2016 10:31 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby Stucuk » Wed Oct 12, 2016 2:58 pm

Permission Denied

You don't have the proper permissions to view this page. Please contact the owner of this project to request permission.


People (Me for example) won't create accounts with 3rd party websites to view documentation.

Btw how are you actually getting comments to be read by doxygen when its not in the format doxygen reads? (The // is ignored by doxygen in favour of bits like //! )
User avatar
Stucuk
 
Posts: 801
Joined: Sat Mar 12, 2005 3:54 pm
Location: Scotland

Re: RFC: (Preliminary) API Documentation Now Online

Postby Julio Jerez » Wed Oct 12, 2016 3:55 pm

Oh I just clicked on the link and got the same error

Permission Denied
You don't have the proper permissions to view this page. Please contact the owner of this project to request permission.


I thought the doc was created after committing code.
how does that work?
Julio Jerez
Moderator
Moderator
 
Posts: 12249
Joined: Sun Sep 14, 2003 2:18 pm
Location: Los Angeles

Re: RFC: (Preliminary) API Documentation Now Online

Postby Stucuk » Wed Oct 12, 2016 5:21 pm

Julio Jerez wrote:I thought the doc was created after committing code.
how does that work?


It wouldn't be straight after. Based on the Original Post description it would check the repository every so often, download the changed files if the source has changed and then rebuild the documentation.

But i don't see how it would work when the source on the repository doesn't use the Doxygen comment format.

While working on NewtonDoc i had to use the following comment style for Doxygen to read comment blocks:
Code: Select all
//! Name: NewtonBodyAddForce
//!
//! Desc: Add the net force applied to a rigid body.
//!
//! Parameters:
//! *const NewtonBody* *bodyPtr - pointer to the body to be destroyed.
//! *const dFloat* *vectorPtr - pointer to an array of 3 floats containing the net force to be applied to the body.
//!
//! Return: Nothing.
//!
//! Remarks: This function is only effective when called from *NewtonApplyForceAndTorque callback*
//!
//! Example: void NewtonApplyForceAndTorque(const NewtonBody* const body, dFloat timestep, int threadIndex)\n
//! {\n
//!   dVector force (0.0f, -9.8f, 0.0f, 0.0f);\n
//!   NewtonBodyAddForce(body, &force[0]);\n
//! }
//!
//! See Also: NewtonBodySetForce, NewtonBodyGetForce, NewtonBodyGetForceAcc


Which generated the following output:
Image
User avatar
Stucuk
 
Posts: 801
Joined: Sat Mar 12, 2005 3:54 pm
Location: Scotland

Re: RFC: (Preliminary) API Documentation Now Online

Postby oliver » Wed Oct 12, 2016 7:13 pm

Stucuk wrote:
Permission Denied

You don't have the proper permissions to view this page. Please contact the owner of this project to request permission.


People (Me for example) won't create accounts with 3rd party websites to view documentation.


The page does not exist anymore because I rearranged the code and branch names
for the PR (that changed the url).

But i don't see how it would work when the source on the repository doesn't use the Doxygen comment format.

It wouldn't. The PR with the Doxygen comments for Newton.cpp has been on unacknowledged on GH for 13 days. Since this morning it will also not merge anymore because Julio pushed changes to Newton.cpp.

If you want to see the latest docu it used to build: https://newton-dynamics.readthedocs.io/en/latest/

The source code for this exact build (mostly the modified Newton.cpp) is here:
https://github.com/olitheolix/newton-dy ... ree/sphinx


It wouldn't be straight after.

Yes, it would be straight after, and works just like CI builds. Whenever someone commits to the repo, GH dispatches webhooks to all configured 3rd party services.

In the case of ReadTheDocs, the repo owner must create an RTD account (free for OSS projects) and link the repo. Then, whenever GH receives a commit it notifies RTD, which will then clone the repo, build the Sphinx documentation, and publish it. The current docu is built from my own GH repo to demonstrate how this would work and look, but I cannot configure GH/RTD credentials for another repo via a PR... the repo owners will have to do that themselves (maybe I was not clear enough on that).
oliver
 
Posts: 36
Joined: Sat Sep 17, 2016 10:31 am

Re: RFC: (Preliminary) API Documentation Now Online

Postby Julio Jerez » Wed Oct 12, 2016 7:39 pm

oliver wrote:It wouldn't. The PR with the Doxygen comments for Newton.cpp has been on unacknowledged on GH for 13 days. Since this morning it will also not merge anymore because Julio pushed changes to Newton.cpp.

I thought I committed all of the merge request.

if the CPP do no merge maybe you can post the c++ file and I can merge them manually using Araxies
which is a powerful merge file merge utility.
Julio Jerez
Moderator
Moderator
 
Posts: 12249
Joined: Sun Sep 14, 2003 2:18 pm
Location: Los Angeles

Next

Return to General Discussion

Who is online

Users browsing this forum: No registered users and 20 guests