docs: general formatting, fix links, cleanups, rewrites #554

chuck-sys · 2020-10-12T19:33:29Z

Details

Add links to types in internal reference
Change the unicode directional single-/double-quotes to ascii ones so
that mac users aren't selectively favoured
Add even more documentation on less documented functions
Make factory documentation visible when it wasn't for so long
Rewrite segments of architecture because it no longer reflected the
current state of the project
Reformat some names to make internal reference links possible

View newly built docs here: https://rocket2.readthedocs.io/en/cheukyin699-update-docs/

- Add links to types in internal reference - Change the unicode directional single-/double-quotes to ascii ones so that mac users aren't selectively favoured - Add even more documentation on less documented functions - Make factory documentation visible when it wasn't for so long - Rewrite segments of architecture because it no longer reflected the current state of the project - Reformat some names to make internal reference links possible Probably should be in separate commits. But they are all under the umbrella of general cleanup.

codecov · 2020-10-12T19:36:25Z

Codecov Report

Merging #554 into master will not change coverage.
The diff coverage is 85.71%.

@@           Coverage Diff           @@
##           master     #554   +/-   ##
=======================================
  Coverage   93.81%   93.81%           
=======================================
  Files          47       47           
  Lines        2669     2669           
  Branches      361      361           
=======================================
  Hits         2504     2504           
  Misses        108      108           
  Partials       57       57

Impacted Files	Coverage Δ
app/controller/command/commands/karma.py	`93.02% <ø> (ø)`
app/controller/command/commands/project.py	`96.95% <ø> (ø)`
app/controller/command/commands/team.py	`86.35% <ø> (ø)`
app/controller/command/commands/user.py	`98.93% <ø> (ø)`
app/controller/webhook/github/core.py	`100.00% <ø> (ø)`
app/model/team.py	`100.00% <ø> (ø)`
app/model/user.py	`100.00% <ø> (ø)`
config/__init__.py	`100.00% <ø> (ø)`
db/dynamodb.py	`90.51% <ø> (ø)`
db/facade.py	`100.00% <ø> (ø)`
... and 3 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 07e20dc...c451e3e. Read the comment docs.

bobheadxi · 2020-10-13T01:20:36Z

Change the unicode directional single-/double-quotes to ascii ones so
that mac users aren't selectively favoured

❤️

bobheadxi · 2020-10-13T01:21:53Z

app/controller/command/commands/team.py

@@ -635,7 +639,8 @@ def refresh_helper(self, user_id) -> ResponseTuple:
        Ensure that the local team database is the same as GitHub's.

        In the event that our local team database is outdated compared to
-        the teams on GitHub, this command can be called to fix things.
+        the teams on GitHub, this command can be called to fix these
+        inconsistencies.


This likely ties into #490 in that we can't remove this command, as we'll always need something to forcibly bring everything in line

Probably need to add a Deprecation Warning whenever someone calls the command.

Oh my point was I dont think we can deprecate it, ever, since we need some way to force a state sync (for example, to add new features - essentially a "migration")

bobheadxi · 2020-10-13T01:22:15Z

conf.py

 # The full version, including alpha/beta/rc tags
-release = '1.0.0'
+release = '2.0.0'


do we even do releases?

Good question. Actually, there is a slim chance that this would come back and bite us. Technically we do releases. We are currently on v2.1.0. I'm thinking that'd be one of the things we'd talk about in the meeting?

Gonna change this to better reflect, but right now docs are generated (and not saved) on master push, soooo rolling release.

I dropped an item in the meeting notes - feel free to add stuff! https://docs.google.com/document/d/1KcH2l6nJKyHoCDe6v6Sl0cLWQWKQQmSLqk_kXvZUsRw/edit

bobheadxi · 2020-10-13T01:22:46Z

config/__init__.py

@@ -118,7 +118,7 @@ def __init__(self, missing_config_fields):
        """
        Initialize a new MissingConfigError.

-        :param: missing_config_fields List of missing config variables
+        :param missing_config_fields: the missing config variables


is there a linter that can catch these documentation errors?

I doubt it.

docs/Architecture.rst

bobheadxi · 2020-10-13T01:26:45Z

This might be because, to center-align the "Rocket 2" header in both GitHub README and the website, I use HTML, which isn't recognized by Sphinx as the top-level header for the page - is there a way to override this? (should be "Rocket 2", not "Usage")

Co-authored-by: Robert Lin <[email protected]>

- set header of readme correctly so that it is picked up by sphinx - use links to make README slightly more readable

…ket2 into cheukyin699/update-docs

chuck-sys · 2020-10-13T02:24:30Z

Is there a way to override this?

I just noticed. Good question. After a bit of read, I think it's safe to say that, yes, there is a way to override this. And no, it's not pretty. See 62a6e82.

It involves creating a dummy header in rst that gets turned invisible by CSS. Normally you can center paragraphs using the .. rst-class:: center directive, which pins the .center class to an element. However, if you do that on a header, it pins the .center class to the entire section (header + everything until the next header). More accurately, it adds the .center class to a div that encompasses the entire section - header and paragraphs below (until the next header). The hack I use has the Rocket 2 section right next to the Usage section so that it ends immediately. That way I can make it invisible using a class (which makes the entire section invisible), but Sphinx reads the section and thinks that the first header still exists.

The raw HTML is still necessary for centering the header up top. At least, some of it is.

bobheadxi · 2020-10-13T02:53:01Z

@cheukyin699 sadly, your approach in 62a6e82 doesn't work on GitHub :( that's why I made the entire top section raw HTML previously - so that it would work on GitHub as well (IMO this is a requirement) - how it should look

chuck-sys · 2020-10-13T03:12:32Z

@rob ahhh. Ohhhh. Welp, back to the drawing board. Might not be possible then.

bobheadxi · 2020-10-13T03:14:48Z

Let's leave that for another PR - can you revert 62a6e82 and I'll approve?

chuck-sys · 2020-10-13T03:16:25Z

Another option:

.. raw:: html

	<style>
		h1:nth-of-type(2) {
			display: none;
		}
	<style>

But that would be way too hacky for me.

chuck-sys · 2020-10-13T03:43:54Z

@bobheadxi reverted

bobheadxi

thank you!!!!

bobheadxi · 2020-10-13T03:49:25Z

Created #555 as follow-up

chuck-sys added 3 commits October 12, 2020 12:52

docs: rm members that should be really private

806189a

docs: add config and attributes

3e4208d

docs: make docstring consistant

b4b3e6a

chuck-sys marked this pull request as ready for review October 12, 2020 20:50

chuck-sys requested review from a team as code owners October 12, 2020 20:50

bobheadxi reviewed Oct 13, 2020

View reviewed changes

Cheuk Yin Ng and others added 3 commits October 12, 2020 18:37

docs: GitHub

8f51524

Co-authored-by: Robert Lin <[email protected]>

docs: minor fixes to readme

62a6e82

- set header of readme correctly so that it is picked up by sphinx - use links to make README slightly more readable

Merge branch 'cheukyin699/update-docs' of github.com:ubclaunchpad/roc…

1a28646

…ket2 into cheukyin699/update-docs

chuck-sys added 3 commits October 12, 2020 20:20

docs: revert broken gh docs

bfaa2ea

docs: revert image that now works

e1bb6cb

docs: fix indenting

c451e3e

bobheadxi approved these changes Oct 13, 2020

View reviewed changes

chuck-sys merged commit 1fa4fa5 into master Oct 13, 2020

chuck-sys deleted the cheukyin699/update-docs branch October 13, 2020 03:44

bobheadxi mentioned this pull request Oct 13, 2020

docs: homepage show wrong header #555

Open

bobheadxi mentioned this pull request Oct 15, 2020

docs: use full links in README, add warning about GitHub #559

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: general formatting, fix links, cleanups, rewrites #554

docs: general formatting, fix links, cleanups, rewrites #554

chuck-sys commented Oct 12, 2020 •

edited

Loading

codecov bot commented Oct 12, 2020 •

edited

Loading

bobheadxi commented Oct 13, 2020

bobheadxi Oct 13, 2020

chuck-sys Oct 13, 2020

bobheadxi Oct 13, 2020

bobheadxi Oct 13, 2020

chuck-sys Oct 13, 2020

bobheadxi Oct 13, 2020

bobheadxi Oct 13, 2020

chuck-sys Oct 13, 2020

bobheadxi commented Oct 13, 2020

chuck-sys commented Oct 13, 2020 •

edited

Loading

bobheadxi commented Oct 13, 2020 •

edited

Loading

chuck-sys commented Oct 13, 2020

bobheadxi commented Oct 13, 2020

chuck-sys commented Oct 13, 2020

chuck-sys commented Oct 13, 2020

bobheadxi left a comment

bobheadxi commented Oct 13, 2020

docs: general formatting, fix links, cleanups, rewrites #554

docs: general formatting, fix links, cleanups, rewrites #554

Conversation

chuck-sys commented Oct 12, 2020 • edited Loading

Details

codecov bot commented Oct 12, 2020 • edited Loading

Codecov Report

bobheadxi commented Oct 13, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bobheadxi commented Oct 13, 2020

chuck-sys commented Oct 13, 2020 • edited Loading

bobheadxi commented Oct 13, 2020 • edited Loading

chuck-sys commented Oct 13, 2020

bobheadxi commented Oct 13, 2020

chuck-sys commented Oct 13, 2020

chuck-sys commented Oct 13, 2020

bobheadxi left a comment

Choose a reason for hiding this comment

bobheadxi commented Oct 13, 2020

chuck-sys commented Oct 12, 2020 •

edited

Loading

codecov bot commented Oct 12, 2020 •

edited

Loading

chuck-sys commented Oct 13, 2020 •

edited

Loading

bobheadxi commented Oct 13, 2020 •

edited

Loading