Add how-to for writing documentation.

[TeresiaOlsson]

I have added a how-to guide for how to write documentation. It includes the new guidelines for what to include and where so it isn't forgotten.

[GamelinAl]

Good idea.

It would be good also to talk about the class-level Attributes / Methods sections which are needed for each class. Something like: "The class docstring should also include Attributes and Methods sections with a one-line summary of each public member."

You should add your new file in the toctree.

[TeresiaOlsson]

Good idea.

It would be good also to talk about the class-level Attributes / Methods sections which are needed for each class. Something like: "The class docstring should also include Attributes and Methods sections with a one-line summary of each public member."

You should add your new file in the toctree.

I thought that information was going to be taken from the docstrings of the attributes and methods now and shouldn't be in the class docstring?

I think we should also add an example of how it should look like to make it easier to understand. I looked at the sextupole but it doesn't really have any methods. The combined function magnet is better but that one has the attribute and method part in the class docstring despite that the exact same information is also written in the docstring for the attributes and methods. So its currently an example of the problem with having to maintain the same docstring in two places.

[GamelinAl]

Yes I agree that we need to maintain twice the one-line docstrings. I don't think it's a big deal but that's my take.

A good exemple is the Accelerator class.

[TeresiaOlsson]

Yes I agree that we need to maintain twice the one-line docstrings. I don't think it's a big deal but that's my take.

A good exemple is the Accelerator class.

I think it's a problem. I predict that people over time will add attributes and methods and forget to update the class docstring so it becomes out of date. That's why I think it would be better if we can make it automatic somehow. Or alternatively add some test or tool which makes that check for us.

[TeresiaOlsson]

Yes I agree that we need to maintain twice the one-line docstrings. I don't think it's a big deal but that's my take.
A good exemple is the Accelerator class.

I think it's a problem. I predict that people over time will add attributes and methods and forget to update the class docstring so it becomes out of date. That's why I think it would be better if we can make it automatic somehow. Or alternatively add some test or tool which makes that check for us.

I will do some trial and error and see if I can figure out some way to avoid having to write the same docstring twice.

[GamelinAl]

Yes I agree that we need to maintain twice the one-line docstrings. I don't think it's a big deal but that's my take.
A good exemple is the Accelerator class.

I think it's a problem. I predict that people over time will add attributes and methods and forget to update the class docstring so it becomes out of date. That's why I think it would be better if we can make it automatic somehow. Or alternatively add some test or tool which makes that check for us.

I will do some trial and error and see if I can figure out some way to avoid having to write the same docstring twice.

Can we say we leave it like this until then?

[TeresiaOlsson]

Yes I agree that we need to maintain twice the one-line docstrings. I don't think it's a big deal but that's my take.
A good exemple is the Accelerator class.

I think it's a problem. I predict that people over time will add attributes and methods and forget to update the class docstring so it becomes out of date. That's why I think it would be better if we can make it automatic somehow. Or alternatively add some test or tool which makes that check for us.

I will do some trial and error and see if I can figure out some way to avoid having to write the same docstring twice.

Can we say we leave it like this until then?

Yes, I just want to add the accelerator example. Maybe a link to the file in the source code would be the best for this case instead of hardcoding the example onto the documentation page.