Convert the Policies section to RST

[RCheesley]

We are in the process of moving this repository to Read the Docs, and to do that we need to convert our pages from Markdown to RST. This issue is to transfer the Policies section: https://contribute.mautic.org/policies. The content of these pages must not change.

You can do this in the current repo, as we've got a folder set up, /docs, which will be used for Read The Docs.

You can build this documentation locally by cloning this repository, and following these steps: https://github.com/mautic/user-documentation/tree/5.x?tab=readme-ov-file#build-documentation-locally. Change into the /docs folder and then (assuming you have DDEV and Docker/Colima installed) type ddev config and select build/html as the root folder when configuring DDEV. Then when complete, type ddev start and it'll give you the link to your local testing environment.

If you need to make a link file to add an external URL, please use the command line tool 'make link'. This will generate a reference macro and a link file for you.

For internal linking check the docs on using the :ref: role for linking within the same document, and using :doc: to link across pages.

Please note: if you see folders called .revs these are old version control files from Grav. Ignore them! (they should be deleted) and instead work on the actual files.

When you've converted the file/s, they need to live within the /docs folder. We can create a structure using sub-folders to organise the sections. You also need to add the pages to the Table of Contents in the index.rst file for them to show on the menu. Docs on the ToC can be found here.
We highly recommend that you use VS Code with Vale installed. Let us know if you have any problems.

Some useful resources:

• https://sublime-and-sphinx-guide.readthedocs.io/en/latest guide to Sphinx/RST formatting
• https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#use-the-external-links-extension how to do external links - always check the /docs/links directory first! You can use the terminal command 'make link' to create the link file automagically.

There are many MD to RST tools out there which can help speed up the process, however you will still need to review your output to ensure it passes our Vale grammar rules. Headings must always be unique, as well.

We use the following for headings:

H1 ###
H2 ***
H3 ===
H4 ---
H5 ~~~

Please ask in #t-education on Slack if you get stuck with anything!

[HappySR]

I'd like to take on the task of converting the Policies section to RST. I believe my understanding of the project's structure and familiarity with RST make me a good fit for this task. Kindly assign me this issue under Hacktoberfest 2024 so I can contribute to the project and fulfill my Hacktoberfest requirement.

[RCheesley]

Thanks for the enthusiastic responses @HappySR ! As we have a lot of interested contributors, I'll open up this PR for others, until you've completed #224.

[autumnlem]

Hi @RCheesley ! Are you still looking for help with this project? I'm new to contributing and this looks like a fun challenge.

[RCheesley]

Hi @autumnlem we're definitely looking for someone to work on this - sorry for the delay in getting back to you! Would you like any guidance on getting started or is the info in the task description sufficient?

[RCheesley]

@favour-chibueze this one's assigned to you but I'm not seeing a PR for this - did you work on it or are we OK to open it up?

[favour-chibueze]

@favour-chibueze this one's assigned to you but I'm not seeing a PR for this - did you work on it or are we OK to open it up?

@RCheesley Here's the PR

The policies page has multiple subsections, and I’m submitting a separate PR for each subsection to make the review process more manageable.

[RCheesley]

OK thanks - is there a section that @autumnlem could take on? I've linked the three PRs that I think relate to this section already.

[favour-chibueze]

OK thanks - is there a section that @autumnlem could take on? I've linked the three PRs that I think relate to this section already.

Yes, she can take on the Trademark