Add sphinx defaults for cookiecutter'd project #2555

hanhanhan · 2020-04-21T15:10:05Z

Description

Add sphinx defaults for cookiecutter'd project

serve, watch + live reload for docs + code file changes
separate _source and _build
add packages and paths to use autodoc
edit/add documentation with examples (both at django-cookiecutter and inside generated project)
add formatted comments in User model for pickup by Sphinx apidoc - fixes Set up auto-generated Sphinx API docs #526
serve docs from a separate docs container for docker build

Rationale

Setting up sphinx documentation is fiddly (and often low priority).

How about a setup that works well from the start?
If it's easier to document as you go, it's more likely to happen.

Use case(s) / visualization(s)

Try:

make livehtml

locally in the docs folder, or in the docs container.

Navigate to port 7000 on your localhost/host (this is in the django-cookiecutter docs now too).

Considerations

~~The make.bat file needs testing. I will.~~ I tested the make.bat file
You may want to structure the docker config differently. To me, it was a tradeoff between using the django base image and inheriting postgres dependencies, and just creating another container. Or serving the docs from the django container, which seemed messy. Maybe you, reviewer person, have a good idea to try instead?

hanhanhan · 2020-04-21T15:13:01Z

docs/document.rst

-
-3. Run the following command: ::
-
-    $ sphinx-apidoc -f -o ./docs/modules/ ./tpub/ migrations/*


Sphinx autodoc is cool, but apidoc seems less useful. So it's there but I don't talk about it.

{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile

hanhanhan · 2020-04-21T15:15:35Z

{{cookiecutter.project_slug}}/docs/Makefile

-SOURCEDIR     = .
-BUILDDIR      = _build
+SPHINXOPTS    ?= 
+SPHINXBUILD   ?= sphinx-build -c .


-c . flag used because conf.py is in different location from source files

hanhanhan · 2020-04-21T15:20:17Z

{{cookiecutter.project_slug}}/{{cookiecutter.project_slug}}/users/models.py

+    """Default user for {{cookiecutter.project_name}}.
+    """

-    # First Name and Last Name do not cover name patterns
-    # around the globe.
+    #: First and last name do not cover name patterns around the globe
    name = CharField(_("Name of User"), blank=True, max_length=255)

    def get_absolute_url(self):
+        """Get url for user's detail view.
+
+        Returns:
+            str: URL for user detail.
+
+        """


Use google style docstring, picked up by apidoc, as an example.
The comments aren't that illuminating, but it shows how this works.

browniebroke · 2020-04-28T11:47:10Z

The diff is now showing the things which have been merged recently, something probably gone wrong in a rebase. Could you try tidying this up?

I don't mind merge commits, and they are usually safer, now it's a bit tricky to review.

hanhanhan · 2020-04-28T15:30:32Z

Yes, I was rebasing as I made some fixes but my commit got buried. I'll drop the non-PR commits.

-serve, watch + live reload for docs + code file changes -update project makefile + make.bat -separate _source and _build -add packages and paths to use autodoc -edit/add documentation with examples (both at django-cookiecutter and inside generated project) -add formatted comments in User model for pickup by Sphinx apidoc -serve docs from a separate docs container for docker build

hanhanhan · 2020-04-30T17:47:04Z

{{cookiecutter.project_slug}}/docs/Makefile


 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -b $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)


"Sphinx only recognizes the -M option if it is placed first."

Include as helper comment only

hanhanhan · 2020-05-18T14:38:25Z

I wish I had used type hints instead of the older style docstrings, but I'd rather just get this closed and (hopefully) come back later than start making more edits.

hanhanhan · 2020-05-18T14:47:34Z

Whoops! I accidentally closed this instead of hitting "comment"!

wadkar · 2020-05-18T14:53:52Z

Whoops! I accidentally closed this instead of hitting "comment"!

Happens to the best of us, no worries 😄

hanhanhan · 2020-06-26T13:32:42Z

I made a "resolve conflicts" that introduced a typo, hence failing tests.
So I just dropped that github-only commit.

Is there anything else I should do to get this ready to merge?

browniebroke · 2020-06-26T14:31:24Z

Is there anything else I should do to get this ready to merge?

Not really at this point. I need to find a bit of time to sit down and review this in properly. Don't worry too much about the conflicts for now, let's do it just before merging (I can do it if needed).

{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile

{{cookiecutter.project_slug}}/docs/_source/howto.rst

browniebroke · 2020-06-26T14:52:40Z

{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile

+    && apt-get install -y texlive-fonts-recommended \
+    && apt-get install -y texlive-latex-extra \
+    && apt-get install -y latexmk \


Do we need these if we don't use latex?

I think it was decided to drop it.

Edit: I just removed this in an additional fixup commit. Do you prefer I squash those? Does it matter?

I commented line 14 -- I meant to comment out lines 14-17 with the note on line 13.
I've seen little notes like that in the project elsewhere.
Should I just delete instead?
I'll fix it in either direction.

Don't worry about squashing, we can do it at merge time.

I don't mind either way, really. I don't use latex anymore, so I'd be in favour of removing them, but that's subjective.

I think @hanhanhan question was whether to keep the lines but comment them out. Personally, I rather delete lines then comment them because, well - that's what git is for! 😄

Git history won't be preserved into projects that will be generated, only in the template code.

Good point - didn't think it from that perspective. This is super helpful PR and I tried out on a demo project recently and I can report that it worked fine with few custom modifications I need for my local docker setup (not relevant to the project).

Thanks a lot @hanhanhan !

sounds good! Co-authored-by: Bruno Alla <browniebroke@users.noreply.github.com>

Co-authored-by: Bruno Alla <browniebroke@users.noreply.github.com>

# Conflicts: # {{cookiecutter.project_slug}}/requirements/local.txt

browniebroke

Gave it a final look, and it looks good.

hanhanhan commented Apr 21, 2020

View reviewed changes

{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile Outdated Show resolved Hide resolved

hanhanhan commented Apr 21, 2020

View reviewed changes

{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile Outdated Show resolved Hide resolved

hanhanhan commented Apr 21, 2020

View reviewed changes

hanhanhan force-pushed the docs branch 6 times, most recently from 09b6601 to 758d66e Compare April 27, 2020 16:23

browniebroke added the enhancement label Apr 28, 2020

hanhanhan force-pushed the docs branch from 758d66e to d159baf Compare April 28, 2020 15:58

hanhanhan force-pushed the docs branch from 78c836a to 3152bda Compare April 30, 2020 17:43

hanhanhan commented Apr 30, 2020

View reviewed changes

Remove latex from sphinx docker build

401ef31

Include as helper comment only

hanhanhan force-pushed the docs branch from 4e74222 to 401ef31 Compare May 18, 2020 14:36

hanhanhan closed this May 18, 2020

hanhanhan reopened this May 18, 2020

hanhanhan force-pushed the docs branch from d821dcc to 401ef31 Compare June 26, 2020 13:29

browniebroke reviewed Jun 26, 2020

View reviewed changes

{{cookiecutter.project_slug}}/compose/local/docs/Dockerfile Outdated Show resolved Hide resolved

{{cookiecutter.project_slug}}/docs/_source/howto.rst Outdated Show resolved Hide resolved

browniebroke reviewed Jun 26, 2020

View reviewed changes

hanhanhan and others added 5 commits June 27, 2020 13:57

Update {{cookiecutter.project_slug}}/compose/local/docs/Dockerfile

8c2f49a

sounds good! Co-authored-by: Bruno Alla <browniebroke@users.noreply.github.com>

Update {{cookiecutter.project_slug}}/docs/_source/howto.rst

916157e

Co-authored-by: Bruno Alla <browniebroke@users.noreply.github.com>

Merge branch 'master' into docs

1961674

# Conflicts: # {{cookiecutter.project_slug}}/requirements/local.txt

Comment out all lines related to LaTeX

bed885f

Missing RUN command in Dockerfile

9af7b3a

browniebroke approved these changes Jul 4, 2020

View reviewed changes

browniebroke merged commit 19c151b into cookiecutter:master Jul 4, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add sphinx defaults for cookiecutter'd project #2555

Add sphinx defaults for cookiecutter'd project #2555

hanhanhan commented Apr 21, 2020 •

edited by browniebroke

Loading

hanhanhan Apr 21, 2020

hanhanhan Apr 21, 2020 •

edited

Loading

hanhanhan Apr 21, 2020 •

edited

Loading

browniebroke commented Apr 28, 2020

hanhanhan commented Apr 28, 2020

hanhanhan Apr 30, 2020

hanhanhan commented May 18, 2020

hanhanhan commented May 18, 2020 •

edited

Loading

wadkar commented May 18, 2020

hanhanhan commented Jun 26, 2020

browniebroke commented Jun 26, 2020

browniebroke Jun 26, 2020

wadkar Jun 26, 2020

hanhanhan Jun 27, 2020 •

edited

Loading

browniebroke Jun 27, 2020

wadkar Jun 27, 2020

browniebroke Jun 29, 2020

wadkar Jun 30, 2020

browniebroke left a comment


		3. Run the following command: ::

		$ sphinx-apidoc -f -o ./docs/modules/ ./tpub/ migrations/*

Add sphinx defaults for cookiecutter'd project #2555

Add sphinx defaults for cookiecutter'd project #2555

Conversation

hanhanhan commented Apr 21, 2020 • edited by browniebroke Loading

Description

Rationale

Use case(s) / visualization(s)

Considerations

Choose a reason for hiding this comment

hanhanhan Apr 21, 2020 • edited Loading

Choose a reason for hiding this comment

hanhanhan Apr 21, 2020 • edited Loading

Choose a reason for hiding this comment

browniebroke commented Apr 28, 2020

hanhanhan commented Apr 28, 2020

Choose a reason for hiding this comment

hanhanhan commented May 18, 2020

hanhanhan commented May 18, 2020 • edited Loading

wadkar commented May 18, 2020

hanhanhan commented Jun 26, 2020

browniebroke commented Jun 26, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hanhanhan Jun 27, 2020 • edited Loading

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

browniebroke left a comment

Choose a reason for hiding this comment

hanhanhan commented Apr 21, 2020 •

edited by browniebroke

Loading

hanhanhan Apr 21, 2020 •

edited

Loading

hanhanhan Apr 21, 2020 •

edited

Loading

hanhanhan commented May 18, 2020 •

edited

Loading

hanhanhan Jun 27, 2020 •

edited

Loading