#252 docs: Combine dev setup docs, refactor organization
Merged by jflory7. Opened by jflory7.
change/refactor-devel-guide  into  master

Download 252.patch

This commit does two things:

  • Combines the two development set-up guide docs into one
  • Refactors the combined page for better organization

I thought it was confusing to have two pages, since they mostly repeated
the other pages. This makes it easier for us to maintain one and only
one source of truth for setting up and developing on Fedora Happiness
Packets.

I also refactored the combined pages and reorganized parts to make it
easier to read. It is a fairly long page, so I used some more
ReStructuredText / Sphinx magic to improve readability where I could.

This page also now conforms to most of the Sphinx docs style guide too:

https://documentation-style-guide-sphinx.readthedocs.io/

Some of these, like filenames, I intentionally ignore because I think
they are quite silly.

Metadata Update from @jflory7:
- Pull-request tagged with: PASSED, improvement, type - docs, type - internal organization

Metadata Update from @jflory7:
- Pull-request tagged with: type - summer coding

@shraddhaag Could you please review this docs PR some time after Monday? I did not add anything new, but I did change some explanations and re-arrange a lot of things. Mostly I want to make sure it is up-to-date on how things are done today and/or if anything could be better explained.

It is also good practice to test it out and make sure it builds too. Since it's been a while since we have worked with the docs, here are two ways to test the docs:

With Pipenv, preferred:

cd docs/
pipenv shell
pipenv install
./test-docs.sh

With regular virtualenv:

# start virtualenv with your preferred method
cd docs/
pip install -r requirements.txt
./test-docs.sh

Once you build the docs, you can open the docs/_build/index.html page in your web browser to see them rendered.

Metadata Update from @jflory7:
- Pull-request tagged with: needs testing
- Request assigned

@jflory7 Hi! Thank you for getting these changes addressed. The docs definitely needed a revamp. I like the idea of getting all development docs in one place to make it more succinct. A special thank you for the Alternatives to Docker section in the setup docs, we were especially behind on that part.

The only thing I see changing in near future are the integration tests. Hopefully after @alishapapun is done with them, we can get that addressed in near future too! :cake:

These changes look great! I'm +1 on merge. :smile:

@shraddhaag Thanks for looking this over! We can definitely revisit the integration tests later on, I agree.

Merging! :ocean:

Metadata Update from @jflory7:
- Pull-request untagged with: needs testing

Pull-Request has been merged by jflory7