Write docs for Core component

[favour-chibueze]

We need to write documentation on the Core component.

https://devdocs.mautic.org/en/latest/components/core.html

[Peacesandy]

Hello @favour-chibueze and @RCheesley Can I take this up, I'd like to work on it.

[RCheesley]

Awesome @Peacesandy please let us know if you need any guidance!

[Peacesandy]

Thank you! Sure, how do I get started please, what is the core component all about?

[RCheesley]

@escopecz could you give any guidance here? The file was added by Alan when we initially started this repo.

[escopecz]

The CoreBundle is a basically the Mautic bundle. Other core bundles are adding some specific feature like Configuration, Category, User bundles. The Core bundle is the only bundle that must be present to have Mautic working. Basically, if there is a PHP class that is used in multiple other bundles, it's added to the CoreBundle. It's hard to describe it easily as it is huge but doesn't really do anything specific, really. It contains all the interfaces and abstract classes that other bundles are implementing and extending. It actually handles themes but that's pretty much the only visible feature it handles.

[Peacesandy]

Okay, thanks for the clarification @escopecz

[Peacesandy]

Hello @escopecz and @RCheesley any guidance on how I can set up the docs on my local machine or can I add the documentation via Github.

@favour-chibueze

[favour-chibueze]

Hello @escopecz and @RCheesley any guidance on how I can set up the docs on my local machine or can I add the documentation via Github.

@favour-chibueze

Have you tried using gitpod? @Peacesandy

[Peacesandy]

@favour-chibueze , I have cloned it to my local machine, should I go ahead and add the documentation and make a PR?

[favour-chibueze]

Yes, please

[Peacesandy]

Okay

[Peacesandy]

@RCheesley and @escopecz which of the files do I do the routing?

[Peacesandy]

Hi @RCheesley @favour-chibueze @escopecz I've not been able to push my changes and I can't create a PR

[RCheesley]

Hi there!

Here's how to set up the docs locally: https://github.com/mautic/developer-documentation-new?tab=readme-ov-file#build-documentation-locally

Here's how to make a PR on GitHub:

1. Fork the repository, by clicking the button you see above all the files when you first land on the repo
2. Clone your fork locally
3. Create a new branch to work on - name it something relevant to what you're working on. In VSCode you do this by clicking on the name of the branch bottom left, and then typing the name of the new branch in the popup that shows.

4. Make your changes, and save the files as you work.
5. Click on the version control icon, and you'll see the changes you've made. Next to each file if you hover over will be a plus icon, which allows you to stage those changes for committing (saving) them. Click it for each file you want to add, then type a commit message in the box above. You can commit one file at a time, a few at a time, or everything - it's better to do things incrementally as you can then easily roll back one specific commit if you make a mistake.

6. Once you've done this, press publish branch and it'll publish the branch on your fork.
7. Come back to this repository and you'll see a green button which tells you that changes have been made on your branch, and inviting you to make a PR
8. Once you are done with making the PR, switch back to the 5.x branch by clicking bottom left again, and selecting 5.x

[Peacesandy]

Thank you so much for your help @RCheesley

After building the documentation and running make HTML, I noticed that the build files are grey because the build is included in gitignore.

Should the changes be made in the build files or component, .rst which is written in markdown

[RCheesley]

Great question! You only need commit the .rst files, anything in /build should not be committed as they are built when we render the documentation.

So, make the changes to your files, use the make html command to rebuild the docs and check that they are working OK (I run DDEV in the /docs folder to have a web server on which to do this - you need to install Docker Desktop/Colima and DDEV to do this, then type ddev config when in the docs folder, and then just accept the defaults, then ddev start and it will give you a local URL to use to check).

Once you're happy everything has rendered as you'd expect it to, then you can commit the .rst files which you edited (and only those files).

[Peacesandy]

Thank you so much @RCheesley

[RCheesley]

HI @Peacesandy how are you getting along, did you need any further help?