DOC: split Contributing page #39367 #39441

David-dmh · 2021-01-27T18:58:50Z

Splited original contributing.rst into 3 separate pages:

Removed information for setting up an environment outside of Docker and created a new file for this purpose.
Removed information for contributing to the codebase and created a new file for this purpose.
Reformatted contributing.rst and renamed as contributing_documentation.rst (containing the remainder of information pertaining to documentation contributions).

jreback · 2021-01-28T02:42:37Z

see the docs build

/home/runner/work/pandas/pandas/doc/source/development/contributing_codebase.rst: WARNING: document isn't included in any toctree
/home/runner/work/pandas/pandas/doc/source/development/contributing_documentation.rst: WARNING: document isn't included in any toctree
/home/runner/work/pandas/pandas/doc/source/development/env_outside_docker.rst: WARNING: document isn't included in any toctree

IOW you are renaming but you have to change the referencing pages themselves.

gustavocmaciel · 2021-01-28T14:24:32Z

@David-dmh , this reference #39367, right? You should specify that on your PR message. This is the template to be used https://github.com/pandas-dev/pandas/blob/master/.github/PULL_REQUEST_TEMPLATE.md

About the changes you've made, I'd like to point a few things I've noticed:

doc/source/development/contributing_codebase.rst should have only the content of the Contributing to the code base section, but it has everything from that section to the end of the file. Contributing your changes to pandas and Tips for a successful pull request shouldn't be there.
The doc/source/development/contributing_documentation.rst file should have only the Contributing to the documentation part and not everything before (and after) that.
It looks like you renamed/deleted the contributing.rst file, but that file should still exist and it should remain basically the same.

David-dmh · 2021-01-28T22:08:44Z

Thank you for the guidelines, I'm working on making the changes.

gustavocmaciel · 2021-01-29T00:11:02Z

doc/source/development/contributing_documentation.rst

+~~~~~~~~~~~~
+
+First, you need to have a development environment to be able to build pandas
+(see the docs on :ref:`creating a development environment above <contributing.dev_env>`).


Can you delete above ? This link will lead to a different page now.

Suggested change

(see the docs on :ref:`creating a development environment above <contributing.dev_env>`).

(see the docs on :ref:`creating a development environment <contributing.dev_env>`).

gustavocmaciel · 2021-01-29T00:44:03Z

doc/source/development/contributing_codebase.rst

+
+If your code is an enhancement, it is most likely necessary to add usage
+examples to the existing documentation.  This can be done following the section
+regarding documentation :ref:`above <contributing.documentation>`.


Now the link text should be documentation instead of above.

Suggested change

regarding documentation :ref:`above <contributing.documentation>`.

regarding :ref:`documentation <contributing.documentation>`.

gustavocmaciel · 2021-01-31T16:58:27Z

About the checks, it also failed the docs build. You have to fix these problems too:

/home/runner/work/pandas/pandas/doc/source/development/contributing_documentation.rst:21: WARNING: duplicate label contributing, other instance in /home/runner/work/pandas/pandas/doc/source/development/contributing.rst
/home/runner/work/pandas/pandas/doc/source/development/contributing_codebase.rst: WARNING: document isn't included in any toctree
/home/runner/work/pandas/pandas/doc/source/development/contributing_documentation.rst: WARNING: document isn't included in any toctree
/home/runner/work/pandas/pandas/doc/source/development/env_outside_docker.rst: WARNING: document isn't included in any toctree
/home/runner/work/pandas/pandas/doc/source/development/contributing.rst:162: WARNING: undefined label: contributing.documentation
/home/runner/work/pandas/pandas/doc/source/development/contributing_codebase.rst:818: WARNING: undefined label: contributing.documentation

Co-authored-by: Gustavo C. Maciel <[email protected]>

David-dmh · 2021-02-03T15:48:47Z

Currently I'm working on being able to build the docs. Three dependencies are not installing (bottleneck, fastparquet, python-snappy). I have made changes in an attempt to rectify the doc build errors mentioned above.

MarcoGorelli · 2021-02-07T10:40:00Z

Hi @David-dmh - how are you trying to create your local development environment? IMO using miniconda is the most straightforward way. Anyway, if show your output, we can help debug

David-dmh · 2021-02-07T16:55:52Z

Thanks for getting back to me @MarcoGorelli . Firstly, as you can see the 'CI / Web and docs' test is failing. It has an output of:
build finished with problems, 5 warnings. Error: Process completed with exit code 1.

I am still having an issue regarding environment setup. I now tried with Miniconda and it still throws the following error: (this is after activating pandas-dev and calling python setup.py build_ext -j 4 ).

C:\Users\User\AppData\Local\Programs\Python\Python38\include\pyconfig.h(59): fatal error C1083: Cannot open include file: 'io.h': No such file or directory C:\Users\User\AppData\Local\Programs\Python\Python38\include\pyconfig.h(59): fatal error C1083: Cannot open include file: 'io.h': No such file or directory C:\Users\User\AppData\Local\Programs\Python\Python38\include\pyconfig.h(59): fatal error C1083: Cannot open include file: 'io.h': No such file or directory error: command 'C:\\BuildTools\\VC\\Tools\\MSVC\\14.28.29333\\bin\\HostX86\\x64\\cl.exe' failed with exit status 2

MarcoGorelli · 2021-02-09T10:53:25Z

Did you install Build Tools for Visual Studio 2017?
Perhaps let's try solving the environment issue first then, can you write on the gitter channel providing information about your setup and what steps you followed?

David-dmh · 2021-02-09T22:01:15Z

Perhaps that is the issue, I installed the 2019 version. Will message via Gitter .

David-dmh · 2021-02-14T23:35:26Z

Hi @MarcoGorelli , still busy chipping away at this one. I have been trying to use docker and it successfully builds pandas after executing docker build --tag pandas-yourname-env . I now need to just run docker run -it --rm -v path-to-pandas-yourname:/home/pandas-yourname pandas-yourname-env.
Now this is likely a trivial issue but I am struggling to make sense of which paths to substitute into the above (to run the container and bind to the local forked repo)? I.e. Could you perhaps give a sample call? I can then just substitute my paths in.

MarcoGorelli · 2021-02-15T09:40:08Z

I think path-to-pandas-yourname should just be the path where you cloned the pandas repo locally

If you use VSCode or PyCharm (pro edition), they have their own ways for developing in remote containers, it might be easier like that https://code.visualstudio.com/docs/remote/containers

David-dmh · 2021-03-06T19:39:32Z

@gcmaciel I created a fresh PR #40130 with regards to this issue. Could you take a look at that code rather when reviewing and let me know of any fixes needed?

MarcoGorelli · 2021-03-06T20:53:06Z

Thanks @David-dmh - OK, I'll close this one in favour of #40130 (in the future, you can just add a new commit, you don't need to open a new PR), I'll aim to review it next week

David-dmh added 18 commits January 27, 2021 18:48

Create env_outside_docker.rst

cfcb23b

Create contributing_codebase.rst

1ab9e0a

Create contributing_documentation.rst

7f35992

Update env_outside_docker.rst

9868cc4

Update contributing_codebase.rst

a545972

Update env_outside_docker.rst

24a2c93

Update contributing_documentation.rst

583da7a

Update contributing_documentation.rst

38276ca

Update contributing_documentation.rst

b50fadf

Update env_outside_docker.rst

76d09bd

Update contributing_codebase.rst

ef4e1e8

Update env_outside_docker.rst

6b6c07d

Update contributing_codebase.rst

832edf4

Update env_outside_docker.rst

646aebf

Delete contributing.rst

7844fd1

DOC: separate page for codebase contributions

5a7633b

DOC: separate page for environment outside Docker

c80eed5

DOC: re-formatted original based on changes

a80d701

jreback added the Docs label Jan 28, 2021

David-dmh added 5 commits January 28, 2021 22:56

Removed sections to only include code base info

f3b2185

Update contributing_documentation.rst

f730ac7

Update contributing_documentation.rst

32e03a9

Update contributing_documentation.rst

37702e0

Create contributing.rst

66398be

gustavocmaciel reviewed Jan 29, 2021

View reviewed changes

Update contributing_codebase.rst

1a7ff19

David-dmh and others added 12 commits February 1, 2021 12:46

Update doc/source/development/contributing_codebase.rst

b716180

Co-authored-by: Gustavo C. Maciel <[email protected]>

Header fix

36e4434

Cross ref

df9b9d0

DOC: update links

46891a7

DOC: update link

4664de4

DOC: Update links

3511700

DOC: update links

0786da2

DOCL update toctree

88f2b07

DOC: update toctree

32c0123

DOC: fix toctree errors

06654df

DOC: fix links

77a68b9

DOC: major fixes

78cf3a3

DOC: fix headers

91ef8d1

David added 2 commits February 13, 2021 02:56

DOC: update

b99c532

Merge branch 'master' into master

86aea46

David-dmh added 4 commits February 17, 2021 17:52

Merge branch 'master' into master

ab12bca

Update contributing.rst

e1ebd75

Update contributing.rst

2dcfc72

Update Dockerfile

9eee9ca

MarcoGorelli closed this Mar 6, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: split Contributing page #39367 #39441

DOC: split Contributing page #39367 #39441

David-dmh commented Jan 27, 2021

jreback commented Jan 28, 2021

gustavocmaciel commented Jan 28, 2021

David-dmh commented Jan 28, 2021

gustavocmaciel Jan 29, 2021

gustavocmaciel Jan 29, 2021

gustavocmaciel commented Jan 31, 2021

David-dmh commented Feb 3, 2021

MarcoGorelli commented Feb 7, 2021

David-dmh commented Feb 7, 2021

MarcoGorelli commented Feb 9, 2021

David-dmh commented Feb 9, 2021 •

edited

Loading

David-dmh commented Feb 14, 2021

MarcoGorelli commented Feb 15, 2021

David-dmh commented Mar 6, 2021

MarcoGorelli commented Mar 6, 2021

	(see the docs on :ref:`creating a development environment above <contributing.dev_env>`).
	(see the docs on :ref:`creating a development environment <contributing.dev_env>`).

	regarding documentation :ref:`above <contributing.documentation>`.
	regarding :ref:`documentation <contributing.documentation>`.

DOC: split Contributing page #39367 #39441

DOC: split Contributing page #39367 #39441

Conversation

David-dmh commented Jan 27, 2021

jreback commented Jan 28, 2021

gustavocmaciel commented Jan 28, 2021

David-dmh commented Jan 28, 2021

gustavocmaciel Jan 29, 2021

Choose a reason for hiding this comment

gustavocmaciel Jan 29, 2021

Choose a reason for hiding this comment

gustavocmaciel commented Jan 31, 2021

David-dmh commented Feb 3, 2021

MarcoGorelli commented Feb 7, 2021

David-dmh commented Feb 7, 2021

MarcoGorelli commented Feb 9, 2021

David-dmh commented Feb 9, 2021 • edited Loading

David-dmh commented Feb 14, 2021

MarcoGorelli commented Feb 15, 2021

David-dmh commented Mar 6, 2021

MarcoGorelli commented Mar 6, 2021

David-dmh commented Feb 9, 2021 •

edited

Loading