What is the best way to contribute on writing examples

Dear all,
I am not sure about rules for asking question here so I apologize in advance because in this topic I am asking several related questions… let me know if I should split this into different thread instead.

Main topic : I would like to contribute on writing some examples.
I have some basic MOS transistors DC analysis examples and I plan on working on an example for a PWM simulation. (If I have time and sufficient help on my questions, I may also publish a code for generating a passive LC ladder Butterworth filter for an arbitrary order)

Question 1 : From which branch should I start ? (master or devel)

For MOS transistor, I have the option of using the readily available BSIM4 model with default values in ngspice. But in order to be more technology relevant, I can provide examples using PTM models.

Question 2 : is it OK to use some of their models in my examples and add them to the library directory ?

Finally, I would like to write the “web” documentation of the examples I plan to publish.
I tried to build the full project from the master branch but did not succeeded to produce the html documentation which is available at PySpice Doc ; so I am not sure about how this online documentation is produced.
Moreover, I have seen that a tool is used to convert m4 files to graphics but did not find where to download it (can’t remember the name…).

Question 3 : how to contribute on the html documentation for my examples ?

Thank you for your help

1 Like

Also can these examples be re-ordered?


It’s strange that the first example when going through the documentation is “Advanced usages”, even before “Basic usages” (but “Basic usages” is just a subcircuit example, which should probably be in a different category)

1 Like

It’s strange that the first example when going through the documentation is “Advanced usages”

Right ! It is alphabetically sorted …


  1. devel branch is not used actually
  2. Yes excepted if we cannot add the files in the repo due to legal issues …
  3. first you can write a Python script for your examples

The documentation process is not documented actually, I never promoted Pyterate and it should be able to generate Jupyter notebook as well …


  • run pip install invoke pyterate
  • LaTeX and dpic will be more difficult but are only needed to generate the whole documentation
  • run the command (in top source directory) invoke doc.make-api and invoke doc.make-examples and cross fingersstrong text

I generated schemas using https://ece.uwaterloo.ca/~aplevich/Circuit_macros

I like the output quality but it is not user friendly …

Thank you for your feedback @fsalvaire
You may have seen, I have proposed a PR for a very simple DC NMOS example.
It is just a “conversion” of the BJT example.

Now I am trying to build the documentation following your instructions

For practical reasons, I am setting up a Docker environment dedicated to that.
However, the “compilation” fails at a very early stage…

I can make a proper Issue report with the Dockerfile but I don’t know if it is relevant to do it here or if it is preferable to create the issue report on github ?
Let me know you preference.

Best regards

@cyber-g I made some improvements on doc … but I was mainly fighting with conda, CI, Windows these last days … good news Pyterate was accepted in conda-forge today !

Well you can report the issue here, but you must use an up to date version of Pyterate.

I plan to add a SVG cache so as to avoid to require the circuit _macros folks.