Contributing to the MTEX documentation edit page

MTEX documentation is maintained by the whole community. Useful contributions include spelling corrections, worked examples, theoretical explanations and special use cases. Contributors automatically appear on the GitHub contributors page.

Each help page is an executable MATLAB script. A good change must therefore improve the explanation and leave the example runnable.

Choose an editing route

A small correction to one page is easiest in GitHub's web editor. Work locally when the change contains executable code, affects several pages or needs a visual preview. Both routes end with a pull request against the development branch.

Edit one page online

Work through these steps in order:

  1. Sign in to GitHub.
  2. Open the help page you want to change.
  3. Follow its edit page link to the corresponding file in the MTEX repository. For example, open this page's source.
  4. Choose the pencil icon in the top right corner, then edit or paste the corrected text.
  5. Select Commit changes or Propose changes. GitHub creates a fork when you do not have write access to the MTEX repository.
  6. Give the change a short description, select Propose changes, and create the pull request.

The button labels can differ slightly between GitHub views. The important outcome is a pull request whose base repository is mtex-toolbox/mtex and whose base branch is develop.

Work on a page in MATLAB

Documentation sources live below the doc directory. Open a page by its filename or relative path when MTEX is on the MATLAB path:

edit doc/GeneralConcepts/Contribute2Doc.m

The editor lets you run each section, investigate the effect of different parameters or input files, and add further analysis steps. Run the complete script before submitting it because later sections may depend on variables created earlier.

A page begins with its title as a %% section. Prose uses comment lines, while uncommented lines are executed and published as code. Use pipes for inline code, as in calcGrains, and include the .html suffix in internal links, as in Clustering.

Make figures earn their place

A generated figure belongs immediately after the code that creates it. Add a sentence that tells the reader what feature or comparison to notice.

Use a static PNG or SVG only when MATLAB cannot draw the concept clearly. The same file must exist in doc/makeDoc/general for offline help and in ~/mtex/web/images for the website. An image present in only one location is missing from the other build.

Preview and validate the change

The MATLAB publish command provides a quick, raw preview:

publish filename

It creates an html folder in the current directory. This preview is useful for basic MATLAB markup, but it does not apply the MTEX website publisher's link handling, navigation or image sizing.

If the website checkout is available, preview the selected page from its matlab directory:

makeDoc('doc','file','Contribute2Doc')

Run the page itself before previewing it, and run the structural checker from the MTEX repository root:

run doc/GeneralConcepts/Contribute2Doc.m
python3 doc/tools/check_doc_structure.py

A full website build republishes every page and rebuilds the navigation. It is much slower and should be reserved for an attended final check.

Submit a reviewable change

A documentation pull request should say what confused the reader, summarize the correction and list the page run or preview used as evidence. Include a before-and-after image when the rendered figure changes.

If the documentation accompanies a user-visible feature or syntax change, update the MTEX release notes as well. Ordinary spelling and clarity fixes do not need a release-note entry.

You may also copy a local change into GitHub's web editor as described above, or send it to an MTEX developer by email. A pull request is preferable because it keeps the discussion and the exact change together.

References

  • GitHub, Editing files, documents the web editor, automatic fork and pull-request workflow used above.
  • MathWorks, Publishing MATLAB code, defines the raw publish preview and its output.

Citing this page. This page is part of the documentation of MTEX, a free and open source MATLAB toolbox for analyzing and modeling crystallographic textures. It was written by The MTEX Developers and is published at https://mtex-toolbox.github.io/Contribute2Doc.html. If you use MTEX, or reuse text or figures from this page, in your research, please cite

F. Bachmann, R. Hielscher, H. Schaeben: Texture Analysis with MTEX - Free and Open Source Software Toolbox, Solid State Phenomena 160 (2010), 63-68. 10.4028/www.scientific.net/SSP.160.63

BibTeX 
@article{bachmann2010mtex,
  author  = {F. Bachmann and R. Hielscher and H. Schaeben},
  title   = {Texture Analysis with MTEX - Free and Open Source Software Toolbox},
  journal = {Solid State Phenomena},
  volume  = {160},
  pages   = {63-68},
  year    = {2010},
  doi     = {10.4028/www.scientific.net/SSP.160.63},
  url     = {https://doi.org/10.4028/www.scientific.net/SSP.160.63}
}

Other papers describing specific MTEX methods are listed under Publications — please cite the one that best fits your application. The MTEX source code is licensed under the GNU General Public License v2.0; the text and figures of this documentation are licensed under CC BY 4.0, which permits reuse — including by automated systems — provided The MTEX Developers and this page are credited.