search

ganga-devs / ganga

Ganga is an easy-to-use frontend for job definition and management
GNU General Public License v3.0
97 stars 159 forks source link

Updated Developer documentation #2327

Closed Kabiirk closed 4 months ago

Kabiirk commented 4 months ago

Hi @egede , @ Ganga Team,

This PR closes issue #2317.

I have made the relevant changes in the .rst files & previewed the output. I also added some more information w.r.t contributing to the Documentation. The Structure is as follows:

Get started with development:

Working on the Codebase

... relevant steps with code ...

Working on the Documentation

... relevant steps with code ....

Few of the outputs are as follows

Output Artifacts

  1. HTML image image image
  2. Text image image image image

Queries

  1. Running Tests While trying to test via make doctest: image make coverage yields the following : image Please let me know if I need to write any test cases for the documentation as well.

  2. Some Warnings Encountered during Building I built the docs using make <target> (where target is html,text etc.). While the docs built successfully & I was able to see my changes, I encountered the following warnings: image image image image As I understand, these warnings are related to paths added using sys.path() in conf.py & the formatting in other .rst files. Is expected behavior ? or do I need to modify conf.py too ?

Please let me know if further adjustments are required before successfully Merging the PR.

Best Regards

mesmith75 commented 4 months ago

Is it better to use the ssh clone rather than https? I usually use ssh for the sake of making it easier to push. Maybe the developer documentation should say to fork the repository first?

Kabiirk commented 4 months ago

@mesmith75 ,

I agree, forking should be the 1st step, before cloning.

I'll also add both the methods in documentation as having both makes sense & enhances documentation further.

As per my understanding, https is easier than ssh, as users need to generate ssh keys & setup the ssh-agent before code can be pulled of pushed with ssh keys, hence https is recommended by GitHub. Some firewalls also block ssh so it may not work sometimes but https works most of the time.

In my opinion ssh is way more secure & well worth the extra effort to setup, because the Keys provide a layer of security. It also 'decouples' your code activity from your account identity as no changes can be made to the account (password etc.) to lock you out even if your private key is stolen.

mesmith75 commented 4 months ago

Great thanks!

Kabiirk commented 4 months ago

Hi @mesmith75 ,

Add both items. The changes to the page is as follows:

  1. Codebase image
  2. Documentation image

Let me know if this is okay to be merged.

mesmith75 commented 4 months ago

Looks good, thanks