contribute.rst 4.61 KB
Newer Older
1
2
.. _contribute:

vla22's avatar
vla22 committed
3
**********************************
4
5
6
Contribute to the developer portal
**********************************

vla22's avatar
vla22 committed
7
Thank you for contributing to the developer portal!
vla22's avatar
vla22 committed
8

vla22's avatar
vla22 committed
9
There are two main ways to contribute to the developer portal:
vla22's avatar
vla22 committed
10

11
Direct Contribution
vla22's avatar
vla22 committed
12
###################
vla22's avatar
vla22 committed
13

14
You can use the `Edit on GitLab` (TODO: need to change a picture!) button to directly contribute to a page.
vla22's avatar
vla22 committed
15
16
17
18
19

.. image:: images/edit-on-gl.png
   :alt: A page on the developer portal, showing the "Edit on GitLab" link in the top right of the page.

After logging in, this will open GitLab's edit page window in which depending on your permissions:
vla22's avatar
vla22 committed
20

vla22's avatar
vla22 committed
21
22
- you could use GitLab's Edit Window to make your changes and push to a branch, then create a Merge Request
- or you could use the fork option(TODO: need to add a picture!) and then follow the same steps: use GitLab's Edit Window to make your changes and push to a branch, then create a Merge Request from your fork to the developer portal project. Note; creation of the fork will be handled automatically.
vla22's avatar
vla22 committed
23
24
25
26

Then, you can follow the Merge Request page for status updates, make new contributions directly or by setting up your local development as described below.


27
Static build
vla22's avatar
vla22 committed
28
############
vla22's avatar
vla22 committed
29

30
First clone the `developer portal repo <https://gitlab.com/ska-telescope/developer.skao.int>`_ from GitLab. We recommend using ssh to clone.
vla22's avatar
vla22 committed
31

vla22's avatar
vla22 committed
32
Then you install dependencies: ``pipenv install --dev``
vla22's avatar
vla22 committed
33

vla22's avatar
vla22 committed
34
You can then make changes to the repository. To build the documentation locally, run: ``pipenv run make html``
vla22's avatar
vla22 committed
35
36
37
38

This will create a subdirectory `/build/html`. To browse the documents created
open `/build/html/index.html` in a web browser.

vla22's avatar
vla22 committed
39
40
41
42
.. note::
   If you've been editing the developer portal files in a different shell window to the one that you run ``pipenv run make html`` in, it will occasionally fail to trigger a full build. Running any command in the shell you're running the make command in will fix this, even if it's as trivial as ``ls``.
   If you're working on the ``.js`` files, you may need to delete the ``/build`` directory for the build to handle the adjustments.

vla22's avatar
vla22 committed
43
44
45
Documentation Guidelines
########################

vla22's avatar
vla22 committed
46
When adding files of any kind to this project, do not use underscores in filenames. Use hyphens instead. Very long filenames are mildly discouraged, as it makes doing cross-references more difficult. Some examples::
vla22's avatar
vla22 committed
47

vla22's avatar
vla22 committed
48
49
   thng.rst // A bit short. What is this page about?
   contrib-guide.rst // Good. Not too long to type, and says what the page is about
50
   development_guidelines_and_policies.rst // Too long, and uses underscores, which are forbidden.
vla22's avatar
vla22 committed
51

52
If you are adding image files, we recommend using a ``/images`` directory in the same directory as the ``.rst`` file you are editing. These directories exist in several locations already. Image and other media files should be named using the same conventions as is used for the ``.rst`` files that generate the pages. Any images added should adhere to the :doc:`SKA contribution guidelines </getting-started/contrib-guidelines>`.
vla22's avatar
vla22 committed
53

54
If you wish to `cross-reference <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_ other pages on the developer portal, you must use the ``:doc:`` syntax. This allows the Sphinx documentation generator to detect broken links within the site. Do not refer to pages within thie site using the syntax for URLs.
vla22's avatar
vla22 committed
55
56
57

We use `Thomas Cokelaer's headings syntax <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#headings>`_; if you find a page that does not conform, please update it as you edit it.

58
We recommend working on a branch and then submitting a merge request. We recommend following the :ref:`branching-policy`.
vla22's avatar
vla22 committed
59
60
61
62
63
64

When you've created a merge request, you can get feedback from a wider number of people by using the "view app" button:

.. image:: images/view-app.png
   :alt: The view app button on GitLab.

vla22's avatar
vla22 committed
65
Clicking this button allows people to view your changes without having to build the documentation themselves. If you need very wide consultation, a ReadtheDocs admin (ask on the `team-system support Slack channel <https://skao.slack.com/archives/CEMF9HXUZ/>`_ to find one) can add your version to the list of version accesible from the site's "versions" dropdown:
vla22's avatar
vla22 committed
66
67
68
69

.. image:: images/rtd-versions.png
   :alt: The Read the Docs version dropdown expanded to show a list of clickable versions.

70
Once you've addressed any comments, remember to pull any updates from the master branch. Then you should be good to merge your request.
vla22's avatar
vla22 committed
71

72
Finally, if you've moved existing pages to a new location, a ReadtheDocs admin can add redirects, so we don't end up with broken links. Redirects should use the "page" type redirect.
vla22's avatar
vla22 committed
73
74

Happy merging!