User API reference guide

  • What should be in User API reference guide?
    • what should be on the web?
    • what should be in the user manual?
    • what should be in Python docstring?
  • Is it possible to make doxygen not so useless for normal user as it is now?
  • How to provide Python IDE with hints or auto completion while using BornAgain classes?

About Python doc string

  • For every class/method we expose to Python, Boost::python automatically generates docstring, which can be accessed in Python
    
    # the command
    print ParticleDecoration.addParticle.__doc__
    
    # will print
    """ 
        addParticle( (ParticleDecoration)arg1, (Particle)p_particle, (ITransform3D)transform [, (float)depth=0 [, (float)abundance=1.0]]) -> None
    
        addParticle( (ParticleDecoration)arg1, (Particle)particle [, (float)depth=0.0 [, (float)abundance=1.0]]) -> None
    """ 
    
  • This doc string can be seen in, for example, PyCharm using ctrl-Q
  • The given doc string has some value, but it doesn't conform epidoc markup language, so PyCharm can't use it to give hints about parameters
  • Also, the doc string is not taken into account by PyCharm during auto-completion

For auto-completion PyCharm uses so called python stubs which he generates by himself from our libBornAgainCore.so

they are located at from ~/.PyCharm30/system/python_stubs
they represent C++ signatures (addParticle(self, ParticleDecoration, *args, **kwargs)) and are useless for auto completion

  • There are ways how to feed PyCharm or any other IDE with our own python stubs to make everything working (auto-completion, parameter hints, etc) but this requires, basically,
    the creation of python stubs by our self for every method we expose to Python.

and I don't see how it can be automatized

Methods used in our Python functional tests

These are the classes/methods we currently use in our Python functional tests. Given list can serve as a hint to the question, what to put in user API reference guide.

Table below is generated with dev-tools/user-api/docstring.py

Crystal Crystal((LatticeBasis)lattice_basis, (Lattice)lattice)
Crystal setDWFactor((float)dw_factor) -> None
FTDistribution2DCauchy FTDistribution2DCauchy((float)omega_x, (float)omega_y)
FormFactorBox FormFactorBox((float)length, (float)width, (float)height)
FormFactorCone FormFactorCone((float)radius, (float)height, (float)alpha)
FormFactorCylinder FormFactorCylinder((float)height, (float)radius)
FormFactorDecoratorDebyeWaller FormFactorDecoratorDebyeWaller((IFormFactor)p_form_factor, (float)dw_h_factor, (float)dw_r_factor)
FormFactorEllipsoid FormFactorEllipsoid((float)radius, (float)width, (float)height, (float)alpha)
FormFactorFullSphere FormFactorFullSphere((float)radius)
FormFactorFullSpheroid FormFactorFullSpheroid((float)radius, (float)height)
FormFactorGauss FormFactorGauss((float)volume)
FormFactorGauss((float)height, (float)width)
FormFactorHemiSpheroid FormFactorHemiSpheroid((float)radius, (float)width, (float)height)
FormFactorLorentz FormFactorLorentz((float)volume)
FormFactorLorentz((float)height, (float)width)
FormFactorParallelepiped FormFactorParallelepiped((float)height, (float)radius)
FormFactorPrism3 FormFactorPrism3((float)height, (float)half_side)
FormFactorPrism6 FormFactorPrism6((float)height, (float)half_side)
FormFactorPyramid FormFactorPyramid((float)height, (float)half_side, (float)alpha)
FormFactorSphere FormFactorSphere((float)radius, (float)height)
FormFactorSphereGaussianRadius FormFactorSphereGaussianRadius((float)mean, (float)sigma)
IFormFactorBorn evaluate_for_q((cvector_t)q) -> complex
evaluate_for_q((cvector_t)arg2) -> None
InterferenceFunction1DParaCrystal InterferenceFunction1DParaCrystal((float)peak_distance, (float)width [, (float)corr_length=0.0])
InterferenceFunction1DParaCrystal setKappa((float)kappa) -> None
InterferenceFunction2DLattice InterferenceFunction2DLattice((Lattice2DIFParameters)lattice_params)
InterferenceFunction2DParaCrystal InterferenceFunction2DParaCrystal((float)length_1, (float)length_2, (float)alpha_lattice [, (float)xi=0.0 [, (float)corr_length=0.0]])
InterferenceFunction2DParaCrystal createHexagonal( (float)peak_distance [, (float)corr_length=0.0 [, (float)domain_size_1=0.0 [, (float)domain_size_2=0.0]]]) -> InterferenceFunction2DParaCrystal
InterferenceFunction2DParaCrystal setDomainSizes((float)size_1, (float)size_2) -> None
InterferenceFunction2DParaCrystal setProbabilityDistributions((IFTDistribution2D)pdf_1, (IFTDistribution2D)pdf_2) -> None
InterferenceFunctionNone InterferenceFunctionNone()
Lattice Lattice()
Lattice((kvector_t)a1, (kvector_t)a2, (kvector_t)a3)
Lattice((Lattice)lattice)
Lattice createTrigonalLattice( (float)a, (float)c) -> Lattice
Lattice getBasisVectorA( (Lattice)arg1) -> kvector_t
Lattice getBasisVectorB( (Lattice)arg1) -> kvector_t
Lattice getBasisVectorC( (Lattice)arg1) -> kvector_t
Lattice setSelectionRule((ISelectionRule)p_selection_rule) -> None
Lattice2DIFParameters Lattice2DIFParameters()
LatticeBasis LatticeBasis()
LatticeBasis addParticle((Particle)particle, (vector_kvector_t)positions) -> None
Layer Layer()
Layer((IMaterial)material [, (float)thickness=0 [, (IDecoration)decoration=None]])
Layer((IMaterial)material, (float)thickness, (IDecoration)decoration)
Layer((Layer)other)
Layer setDecoration((IDecoration)decoration) -> None
setDecoration((IDecoration)decoration) -> None
LayerRoughness LayerRoughness()
LayerRoughness((float)sigma, (float)hurstParameter, (float)latteralCorrLength)
MaterialManager getHomogeneousMagneticMaterial( (str)name, (complex)refractive_index, (kvector_t)magnetic_field) -> IMaterial
getHomogeneousMagneticMaterial( (str)name, (float)refractive_index_delta, (float)refractive_index_beta, (kvector_t)magnetic_field) -> IMaterial
MaterialManager getHomogeneousMaterial( (str)name, (complex)refractive_index) -> IMaterial
getHomogeneousMaterial( (str)name, (float)refractive_index_delta, (float)refractive_index_beta) -> IMaterial
MesoCrystal MesoCrystal((IClusteredParticles)particle_structure, (IFormFactor)form_factor)
MultiLayer MultiLayer()
MultiLayer addLayer((Layer)p_child) -> None
MultiLayer addLayerWithTopRoughness((Layer)layer, (LayerRoughness)roughness) -> None
Particle Particle()
Particle((IMaterial)p_material, (IFormFactor)form_factor)
Particle((IMaterial)p_material, (IFormFactor)form_factor, (ITransform3D)transform)
ParticleBuilder ParticleBuilder()
ParticleBuilder plantParticles((ParticleDecoration)decor) -> None
ParticleBuilder setPrototype((Particle)particle, (str)name, (StochasticParameter_t)param [, (float)scale=1.0]) -> None
ParticleCoreShell ParticleCoreShell((Particle)shell, (Particle)core, (kvector_t)relative_core_position)
ParticleDecoration ParticleDecoration()
ParticleDecoration addInterferenceFunction((IInterferenceFunction)interference_function) -> None
ParticleDecoration addParticle((Particle)p_particle, (ITransform3D)transform [, (float)depth=0 [, (float)abundance=1.0]]) -> None
addParticle((Particle)particle [, (float)depth=0.0 [, (float)abundance=1.0]]) -> None
ParticleDecoration addParticleInfo((ParticleInfo)info) -> None
ParticleDecoration setTotalParticleSurfaceDensity( (IDecoration)arg1, (float)surface_density) -> None
PositionParticleInfo PositionParticleInfo((Particle)particle, (kvector_t)position [, (float)abundance=0])
ResolutionFunction2DSimple ResolutionFunction2DSimple((float)sigma_x, (float)sigma_y)
Simulation Simulation()
Simulation getIntensityData( (Simulation)arg1) -> IntensityData
Simulation runSimulation( (Simulation)arg1) -> None
Simulation setBeamIntensity((float)intensity) -> None
Simulation setBeamParameters((float)lambda, (float)alpha_i, (float)phi_i) -> None
Simulation setDetectorParameters((IntensityData)output_data) -> None
setDetectorParameters((int)n_phi, (float)phi_f_min, (float)phi_f_max, (int)n_alpha, (float)alpha_f_min, (float)alpha_f_max [, (bool)isgisaxs_style=False]) -> None
setDetectorParameters((object)params) -> None
Simulation setDetectorResolutionFunction((IResolutionFunction2D)p_resolution_function) -> None
Simulation setSample((ISample)sample) -> None
SimulationParameters SimulationParameters()
StochasticDoubleGaussian StochasticDoubleGaussian((float)average, (float)std_dev)
StochasticSampledParameter StochasticSampledParameter((StochasticParameter_t)par, (int)nbins, (float)xmin, (float)xmax)
StochasticSampledParameter((StochasticParameter_t)par, (int)nbins [, (int)nfwhm=3])