Contributing to fortran-lang.org#

Fortran-lang.org is open-source and contributions are welcome!

Introduction#

How is the site written?

The content of the website is primarily written in a combination of Markdown (Myst flavoured), HTML and YAML (for data). This source is compiled to produce pure HTML which is what you see on the final website.

The website is static which means that once built, the content on the site is the same for all users; this is in contrast to many websites that are dynamic, meaning they can serve different content depending on the user and the inputs supplied by the user.

Structural components of the website are written in the Sphinx Static site generator for static features, and JavaScript for dynamic features.

Do I need to know HTML to contribute?

The majority of the site content is written in Markdown, a simple markup language for formatting text - don't worry if you haven't used it before, it's very easy to pick up!

How is the site built?

The Fortran-lang site uses the Python-based Sphinx static site generator to compile the RST,Markdown and HTML files. It is recommended for contributors to install Python on your development computer so that changes can be previewed locally, however this is not mandatory since site previews can be generated during the pull request process (see below for more information). See README.md for how to setup Sphinx and build the site.

The GitHub repository default branch only ever contains the 'source code' for the website, not the final compiled result; an automated service compiles this source code every time an update is pushed and stores the compiled result on the gh-pages branch which is served up at https://fortran-lang.org.

Therefore, as a contributor you only need to upload changes to the site source code and not the compiled result, because this is built automatically from the source code on the default branch.

Workflow#

Contributions to the site are made by pull request to the github repository: fortran-lang/webpage.

The workflow for doing so takes the following form:

  1. Create/update a personal fork of webpage

  2. Create a new branch in your fork

    • The branch name should concisely describe your contribution, e.g. fix-spelling-homepage, update-compiler-info

  3. Perform your changes on the local branch

  4. Push your modified branch to your fork

    • e.g. git push --set-upstream origin fix-spelling-homepage

  5. Create a pull request in the fortran-lang/webpage from your modified fork branch

Note: Before opening a pull request you must build your changes locally using Sphinx (see README.md) to verify that your changes build correctly and render as you expect.

Note: You can continue to push changes to your fork branch after you open a pull request - the pull request will update accordingly

Your pull request will be reviewed by other members of the community who may request changes. GitHub provides an easy interface on its website to apply (or reject) any reviewer-suggested changes with a click of a button. This avoids having to manually copy suggestions to your local copy and push back again. If you use the "Commit suggestion" button, you will need to update the local copy on your computer using git pull if you intend to push more edits from your computer.

Once your pull request is approved, usually by at least two other community members, it will be merged into the webpage default branch by the maintainers at which point it will be published to the fortran-lang.org site.

If required, the repository maintainers can build a public preview of your proposed changes which will be available to view at fortran-lang.org/pr/<pr_id>/ where <pr_id> is the numeric identifier of your pull request.

This allows reviewers to directly view the generated result of your PR.

Note: if you push subsequent commits to your pull request branch, you must rebuild the pull request preview by commenting on the pull request with '#build_preview'.

After a pull request has been merged and successfully rendered, the workflows will delete the preview build.

Note: if your pull request preview link doesn't work or doesn't update after re-building, try adding a random parameter to the end of the URL, e.g. https://fortran-lang.org/pr/98?v=2 - the name and value of the parameter don't matter, but use different values for each update. This will force the GitHub content delivery network to serve you an updated version instead of a cached version which is out-of-date.

Style guide#

Markdown#

  • Place code excerpts in code blocks, denoted by back ticks (```). Use inline code style (`code`) for inline code excerpts, programming language keywords, variables names and file names.

  • Have no more than one sentence per source-code line, and break-up long sentences across multiples lines - this is important to avoid large git diffs and code review blocks on github.

Icon packs#

Icons are an easy way to improve page aesthetic by breaking-up otherwise monotonic text passages and drawing attention to headings or key information.

Three icon packs are available for use on fortran-lang.org:

Example: Font awesome

<i class="fas fa-info-circle"></i>

Example: Sphinx design Myst directives

{octicon}`book;1em;sd-text-info`

Visit the respective websites to browse available icons.

Page contents#

It is sometimes helpful to display hyperlinked page contents for lengthy pages. The page TOC tree has been automated and will generate the TOC of the current page. Whereas the method to generate TOC of the entire directory on Fortran-lang.org is:

For pages in MD:

add the toc tree directive in md at the end of the index page of the directory with the names of the all files in that directory.

````{toctree}  
:hidden:
ARRAY_index 
````

Tutorials#

Guidelines for mini-book content.

General#

Use the book layout.

Follow the Markdown guidelines.

Code style#

Use two spaces for indentation, indenting bodies of units but keeping the contains statement at the same level as its module or type. Try to limit line length to 90 characters. These considerations should make the code more readable and easier to view on devices with smaller viewport widths.

module m
  implicit none
  private
  public :: a_t

  type :: a_t
    integer :: val
  contains
    procedure :: func
  end type a_t

contains

  subroutine func(self)
    class(a_t), intent(in) :: self
    if (self%val > 0) then
      print *, self%val
    end if
  end function func

end module m

Each code block should have a base indentation level of 0, even if it would be indented if put into a larger context.

integer :: i1  ! yes
  integer :: i2  ! no

Avoid vertically aligning :: and inline comments since this adds maintenance burden and pushes the line length in most cases.

If a code block contains lines that are not valid Fortran, leave it as a language-less code block to avoid the syntax highlighter's red boxes.

module <module name>
...
end module <module name>

Feel free to omit spacing in expressions where it helps with readability, but generally include whitespace around operators.

y1 = a * b
y2 = a*b + c*d  ! instead of a * b + c * d
y3 = a**2 + 1
y4 = (a*b + c*d) / 2
s3 = s1 // s2

Generally add a space after commas, except when indexing with short index values or variables names.

a(:,1)
a2(1:10, 2:5)
b(i,j)
b2(long_i_name, long_j_name)
b3(i + 2, j)
call some_subroutine(a, b, an_option=.false.)
c = [1, 2, 3, 10]
d = [(i, i = 1, 10)]
do i = 1, 10
! ...

Other situations besides simple indexings where white space can be omitted:

  • Aliasing in imports

    use, intrinsic :: iso_c_binding, only: sp=>c_float, dp=>c_double

  • String concatentation

    print *, 'hello '//'world'

  • Accessing components (attributes) of derived types

    p%x
p%calc_something(a, b)

  • Around = when passing keyword arguments

    call sr(a, b, c=3)
point = t_point(x=1., y=2.)
character(len=:), allocatable :: s

Capitalize the first letter for inline comments except for trailing inline comments that only consist of one word or a short phrase.

! Compute new values
y = m*x + b  ! meters

These code style recommendations are similar to those in the DFTB+ style guide.

Text#

Use sentence case (as opposed to title case) for page and section titles.

Use emphasis (*emphasis*/_emphasis_, rendered as italic) for key words/phrases when they are first introduced, for emphasis, ...

Avoid use of strong (**strong**, rendered as bold) within paragraphs, since bold style is used for headings, drawing attention to examples (Example:), admonition/aside titles, etc.

Make use of the admonition/aside (note, tip, important) where appropriate.

  • to add a note to md document use:

::::{note}
extra information, something that might appear in a footnote
:::::

  • to add a tip to md document use:

::::{tip}
information about best practices, practical tips
:::::

  • to add an important text to md document use:

::::{importrant}
warnings, things to avoid, etc.
:::::

Prefer including the Oxford comma. It usually makes things more clear.

Fortran is fast, fun, and famed.