Contributing¶

OptiDocs always welcomes contributions and changes. Whether you want to add a new page, add more to a section, or change an image, your contributions are welcome.

Things to know¶

rST¶

OptiDocs' source documents are written in reStructuredText (rST). rST is a markup system originally used in Python but has since been expanded to general use. In order to write or contribute to OptiDocs, you must be familiar with rST. rST is not Markdown, and Markdown is not rST. You should start here; only use quick "cheatsheets" once you are comfortable with the syntax and caveats.

Sphinx¶

Sphinx is used for generating the documentation. Sphinx is widely used, from the Linux kernel to small project documentation. You do not need to be highly knowledgeable about Sphinx, but it is important to be aware of what it is and what it offers. Sphinx is not rST. Sphinx takes in rST documents to generate cohesive and interconnected documentation.

Sphinx-Immaterial (pypi, github, kitchen sink) is the theme used for OptiDocs. This theme includes some unique features that OptiDocs takes advantage of, so you should learn the theme-specific options. Specifically, the .. md-tab-set and custom checkbox styles.

git¶

OptiDocs uses git as the version control system. You must be familiar with how git works. You should be familiar with how merge requests (also called pull requests) work. There is no "develop" branch, only "master".

GitLab¶

OptiDocs' source is on GitLab, a source code hosting website. GitLab is not the same as GitHub. You will need a GitLab account to contribute. For help using GitLab, see https://docs.gitlab.com/.

Browsing the source¶

The source documents for OptiDocs are always open-source and are located at https://gitlab.com/whoatemybutter/optifinedocs.git. You can view any original rST document there. GitLab also offers a preview function when viewing rST files.

Creating issues¶

You can create an issue about anything you want, from a typo to an overhaul of a section of pages. Read about issues and how to create them here. You can also label your issues appropriately so they can be better organized and worked on.

Contributing directly¶

You can modify the OptiDocs source code and merge it back into the master branch yourself, instead of creating an issue and waiting for it to be completed by someone else. There are two main ways to do this:

1. Creating an isolated fork and merging your changes.

2. Making a merge request from an issue.

Standalone and merge¶

You should create an issue about the change you want to make first. This way, your merge request can be linked to it directly. Standalone merge requests are OK, but issues are heavily preferred.

First, you will need to make a clone of the OptiDocs source repository; this is called forking:

git clone https://gitlab.com/whoatemybutter/optifinedocs.git

The repository's name is optifinedocs, not optidocs.

Make the changes you would like to make to the repository. Remember, this is git, so you need to add and commit, too.

Upload your forked repository to a GitLab repository. Next, you will need to make a merge request (MR or PR). GitHub calls it a pull request, GitLab calls it a merge request; they are the same thing. You can first read GitLab's documentation on merge requests and on creating them. Once your merge request has been made, please wait for a review.

Link to issue¶

Find or create the relevant issue to which you would like to contribute. On the OptiDocs GitLab, merge request branches should have documentation built for them automatically by ReadTheDocs.

Style guide¶

Checkboxes¶

In Syntax's string matching section, you may notice some green checks and red crosses. To reproduce this, use this rST:

.. task-list::
    :class: cross-check
    :custom:

    - [x] yes
    - [x] check
    - [ ] no
    - [ ] cross

Admonitions¶

There are 4 custom admonitions you can use:

.. location::

    file location of relevant subject

.. notconfused::

    different subject that people may confuse with

.. legacy::

    this is a legacy property and should not be used; this does not require body text

.. default::

    this is the default value for this property key

Headers¶

From highest importance to lowest:

1. #

2. =

3. -

4. ~

5. ^

6. " (almost never used; if your nesting is this deep, you likely need to re-think your approach!)

Header underline length must equal the length of the header's text.

Headers are in sentence case (Anniversary cape, Custom GUI, Special thingy). Do not start headers with articles (a, the).

For more examples, refer to the Wikipedia page MOS:HEADCAPS.

Text, prose¶

Be neutral and present information as if you are speaking to someone who has not used OptiFine before. Always link to specific features (CIT, CTM, etc.). Link to glossary terms (using :term:`myword`) if applicable.

For indentation, use either a tab character or 4 spaces. It does not matter, as long as it is consistent in the document.

Lists¶

Capitalize the first word and end entries with punctuation.

Tables¶

Use .. csv-table:: or .. list-table:: where possible. If you can, avoid the "="-based tables.